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1.0  Introduction 

The  Simulating  WAves  Nearshore  (SWAN)  model  is  a  numerical  wave  model  used  to  obtain 
realistic  estimates  of  wave  parameters  in  coastal  areas,  lakes  and  estuaries  from  given  wind,  bottom, 
and  current  conditions.  The  model  is  based  on  the  wave  action  balance  equation  (or  energy  balance 
in  the  absence  of  currents)  with  sources  and  sinks.  SWAN  is  a  third-generation  wave  model  with 
first-,  second-  and  third-generation  options. 


2.0  Application 

2.1  Description  of  SWAN  Functionality 

The  following  wave  propagation  processes  are  represented  in  SWAN: 

•  Rectilinear  propagation  through  geographic  space; 

•  Refraction  due  to  spatial  variations  in  bottom  and  current; 

•  Shoaling  due  to  spatial  variations  in  bottom  and  current; 

•  Blocking  and  reflections  by  opposing  currents; 

•  Transmission  through,  blockage  by,  or  reflection  against  sub-grid  obstacles. 

The  effects  of  currents  and  sub-grid  obstacles  are  not  treated  in  this  manual  but  are  available  in 
SWAN. 

The  following  wave  generation  and  dissipation  processes  are  represented  in  SWAN: 

•  Generation  by  wind; 

•  Dissipation  by  whitecapping; 

•  Dissipation  by  depth-induced  wave  breaking; 

•  Dissipation  by  bottom  friction; 

•  Wave-wave  interactions  (quadruplets  and  triads); 

•  Obstacles. 

In  addition,  the  wave-induced  set-up  of  the  mean  sea  surface  can  be  computed  in  SWAN.  Wave 
induced  set-up  and  transmission/blockage/reflection  are  not  treated  in  this  manual  but  are  available 
in  SWAN. 

Cycle  ID  of  SWAN  is  stationary,  optionally  non-stationary,  and  formulated  in  Cartesian  (small 
scale)  or  spherical  (small  and  large  scale)  coordinates.  The  stationary  mode  should  be  used  only  for 
waves  with  a  relatively  short  residence  time  in  the  computational  area  under  consideration.  In  other 
words,  the  travel  time  of  the  waves  through  the  region  should  be  small  compared  to  the  time  scale 
of  the  geophysical  conditions  such  as  wave  boundary  conditions,  wind,  tides  and  storm  surge.  A 
quasi-stationary  approach  may  be  taken  with  stationary  SWAN  computations  in  a  time- varying 
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sequence  of  stationary  conditions.  For  one-dimensional  (geographical)  situations  SWAN  may  be 
run  in  1  -D  mode. 


2.2  Changes  and  Compatibility  Relative  to  Previous  Version 

The  previous  version  of  SWAN  is  40.01 .  The  present  version  of  SWAN  is  40. 1 1 . 


2.2.1  Scientific  Changes 


SWAN  can  now  compute  waves  on  scales  much  larger  than  coastal  scales.  To  accomplish  this, 
SWAN  uses  more  accurate  numerical  propagation  schemes  (see  below),  and  it  can  compute  on 
spherical  coordinates  (longitude,  latitude),  allowing  calculations  in  laboratory  situations,  coastal 
regions,  shelf  seas  and  oceans,  but  not  harbors.  It  must  be  emphasized  that  on  oceanic  scales 
SWAN  is  certainly  less  efficient  than  WAVEWATCH  ITI  and  probably  also  less  efficient  than 
WAM  (see  Section  3.0). 

In  addition  to  transmitting  waves  through  obstacles,  SWAN  can  now  reflect  waves  against  obstacles 
such  as  coastlines  or  breakwaters. 

In  the  formulation  of  depth-induced  breaking,  the  option  of  using  a  variable  wave  height-to-depth 
ratio  has  been  removed,  as  it  did  not  improve  the  SWAN  results  (input  of  previous  SWAN  versions 
is  still  accepted  by  SWAN  40. 1 1  but  not  supported). 


2.2.2  Numerical  Changes 

More  accurate  propagation  schemes  (less  diffusive)  have  replaced  the  Backward  Space,  Backward 
Time  (BSBT)  propagation  scheme: 

•  The  2nd  order  upwind  S&L  scheme  (for  non-stationary  computations  with  3rd  order 
diffusion); 

•  The  Second  ORder  UPwind  (SORDUP)  scheme  (for  stationary  computations  with  3rd  order 
diffusion). 

These  new  schemes  are  default,  but  the  old  first  order  upwind  BSBT  scheme  (for  stationary  and 
non-stationary  computations  with  first  order  diffusion)  is  still  available. 

The  approximation  of  the  bathymetry  in  the  refraction  computations  has  improved.  To  give  robust 
(but  not  necessarily  accurate)  results  in  case  of  poor  resolution  in  bathymetry,  currents  or  the  wave 
field  itself,  the  user  can  activate  a  limiter  to  avoid  waves  turning  over  more  than  90°  in  one  spatial 
grid  step. 
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2.2.3  Configuration  Changes 

In  addition  to  the  existing  option  of  nesting  in  WAM,  SWAN  can  now  also  be  nested  in 
WAVEWATCH IH  (not  fully  tested  yet). 

The  SWAN  code  is  now  written  completely  in  Fortran90,  except  that  occasionally  the  number  of 
continuation  lines  exceeds  19.  Therefore,  SWAN  can  now  operate  on  all  platforms  that  support 
FORTRAN90  (including  Linux).  In  addition,  FORTRAN77  compilers  cannot  be  used  to  install 
SWAN  in.  There  are  no  other  major  configuration  changes. 


2.2.4  Compatibility 

SWAN  version  40. 1 1  is  fully  downward  compatible.  The  results  may  vary  from  results  with 
previous  versions  because  of  the  new  propagation  schemes,  improved  bathymetry  approximations 
for  refraction  and  bug  fixes. 


2.3  Relation  to  WAM,  WAVEWATCH  III  and  Others 

The  basic  scientific  philosophy  of  SWAN  is  identical  to  that  of  WAM.  SWAN  is  a  third-generation 
wave  model,  just  as  WAM  (Cycle  3  and  4)  is,  and  it  uses  the  same  formulations  for  the  source 
terms  (just  like  TOMAWAC)  and  some  additional  formulations,  primarily  for  shallow  water. 
However,  the  numerical  techniques  are  very  different,  although  SWAN  shares  the  code  for  the 
quadruplet  interactions  with  WAM  that  are  originally  from  Hasselmann  et  al.  (1985)  and  somewhat 
adapted  by  Tolman  (personal  communication,  1993).  WAVEWATCH  HI  also  uses  different 
numerical  techniques  and  different  formulations  for  the  wind  input  and  whitecapping. 

This  close  similarity  can  be  exploited  in  the  sense  that  scientific  findings  with  one  model  can  be 
shared  with  the  others.  SWAN  can  be  readily  nested  in  WAM  and  WAVEWATCH  HI  (the 
formulations  of  WAVEWATCH  HI  have  not  (yet)  been  implemented  in  SWAN). 

If  SWAN  is  nested  in  WAM  or  WAVEWATCH  ID,  then  the  boundary  conditions  for  SWAN 
provided  by  WAM  or  WAVEWATCH  IH  may  not  be  model  consistent  even  if  the  same  physics  are 
used.  This  may  be  due  to  numerical  techniques  or  implementation  for  the  geographic  area  (spatial 
and  spectral  resolutions,  coefficients  etc.).  Generally  the  deep-water  boundary  of  the  SWAN  nest 
must  be  located  in  WAM  or  WAVEWATCH  ID  where  shallow  water  effects  do  not  dominate  (to 
avoid  too  large  discontinuities  between  the  two  models).  Also,  the  spatial  and  spectral  resolutions 
should  not  differ  by  more  than  a  factor  of  two  or  three.  If  a  finer  resolution  is  required  a  second  or 
third  nesting  may  be  needed. 
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2.4  Directory  Structure 

2.4.1  Model  Run  Files  and  Routines 

The  user  has  access  to  the  following  files  through  the  SWAN  web  site 
(http://swan.ct.  tudelft.nl/home.htm ): 

In  subdirectory  pro2rams: 

SWAN  modules  containing 


global  variables: 

swmodl.for 

SWAN  main  program: 

swanmain.for 

SWAN  preparation  routines: 

swanprel.for 

swanpre2.for 

SWAN  computation  routines: 

swancoml.for 

swancom2.for 

swancom3.for 

swancom4.for 

swancom5.for 

swancomi.for 

SWAN  output  routines: 

swanoutl.for 

swanout2.for 

swanout3.for 

SWAN  service  routines: 

swanser.for 

Installation  dependent 
subroutines: 

ocpids.for 

Command  reading  routines: 

ocpcre.for 

Dynamic  pool  routines: 

ocpdpn.for 

Plot  routines: 

ocplot.for 

Miscellaneous  routines: 

ocpmix.for 

Include  files  containing  common 
block  variables: 

ocpcomml.inc 
ocpcomm2.inc 
ocpcomm3.inc 
ocpcomm4.inc 
swcomm  1  .inc 
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swcomm2.inc 

swcomm3.inc 

swcomm4.inc 

poolcomm.inc 

timecomm.inc 

Run  procedure  on  DOS  system: 

swan.bat 

Run  procedure  on  Unix  system: 

swan.unx 

Command  file  editing  support: 

swan.edt 

In  subdirectory  test  cases: 

For  tests: 

files  with  an  extension  .swn 
files  with  an  extension  .bot 

In  subdirectory  util: 

For  conversion  of  spectra: 

convert  ld.for 

cvspecld.for 

cvspec2d.for 

For  conversion  from  DOS  to  Unix: 

dos2unix 

dos2unix.readme 

3.0  Limitations  and  Assumptions 

3.1  Computer  Limitations  and  Requirements 

Most  of  the  numerical  data  used  by  SWAN  resides  in  the  dynamic  data  pool.  Its  size  is  set  at  the 
time  of  SWAN  installation.  Sometimes  this  pool  is  too  small.  If  so,  the  following  message  appears 
in  the  print  file: 

"Terminating  error:  array  is  too  small" 

If  this  error  message  appears,  the  user  must  reduce  the  number  of  computational  nodes  or  increase 
MXPOOL.  In  such  cases,  the  command  POOL  is  sometimes  useful.  This  command  is  a  diagnostic 
tool  that  gives  the  size  of  the  data  pool  in  the  user’s  implementation  of  SWAN  (diagnostic 
information  is  given  in  the  print  file). 

To  run  the  SWAN  program  for  the  test  cases,  55  Mb  of  free  internal  memory  is  recommended.  For 
more  realistic  cases  100  to  500  Mb  may  be  needed,  whereas  for  simpler  stationary  or  1-D  cases 
significantly  less  memory  is  needed  (less  than  5  Mb  for  1-D  cases).  The  number  of  files 
addressable  by  the  DOS  system  should  be  at  least  twenty,  therefore  the  command:  FDLES=20  (or 
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some  higher  number,  if  necessary)  should  be  included  in  the  file  configuration  system  of  the  DOS 
operating  system. 


3.2  Model  Limitations 

Diffraction  is  not  modeled  in  SWAN,  so  SWAN  should  not  be  used  in  areas  where  variations  in 
wave  height  are  large  within  a  horizontal  scale  of  a  few  wavelengths.  Because  of  this,  the  wave 
field  computed  by  SWAN  will  generally  not  be  accurate  in  the  immediate  vicinity  of  obstacles  and 
certainly  not  in  harbors. 

SWAN  does  not  calculate  wave-induced  currents.  If  relevant,  such  currents  should  be  provided  as 
input  to  SWAN  (e.g.  from  a  hydrodynamic  model,  which  can  be  driven  by  waves  from  SWAN  in 
an  iteration  procedure).  As  an  option  SWAN  computes  wave-induced  set-up.  In  a  (geographic)  1- 
D  case,  the  computations  are  based  on  exact  equations.  In  2-D  cases,  the  computations  are  based  on 
approximate  equations.  The  effects  of  wave-induced  currents  are  ignored  and  in  1-D  cases  they  do 
not  exist. 

The  Lumped  Triad  Approximation  (LTA)  for  the  triad  wave-wave  interactions  seems  to  depend  on 
the  width  of  the  directional  distribution  of  the  wave  spectrum.  The  present  tuning  in  SWAN  (for 
default  settings  see  command  TRIAD,  Section  4.12.9.6)  seems  to  work  reasonably  well  in  many 
cases,  but  it  has  been  obtained  from  observations  in  a  narrow  wave  flume  (long-crested  waves). 


The  Discrete  Interaction  Approximation  (DIA)  for  the  quadruplet  wave-wave  interactions  also 
seems  to  depend  on  the  width  of  the  directional  distribution  of  the  wave  spectrum  as  well  as  the 
frequency  resolutions.  It  works  reasonably  well  in  many  cases,  but  is  a  poor  approximation  for 
long-crested  waves  (narrow  directional  distribution)  and  frequency  resolutions  different  from  10% 
(see  command  CGRID,  Section  4.12.6.1),  WAM  and  WAVEWATCH  HI  share  this  problem. 

SWAN  Version  40.11  can  be  used  on  any  scale  relevant  for  wind  generated  surface  gravity  waves 
(high  quality,  third  order  diffusion  propagation  and  Cartesian  or  spherical  coordinates).  However, 
SWAN  is  specifically  developed  for  coastal  applications  that  would  normally  not  require  such 
flexibility  in  scale.  The  reasons  for  providing  SWAN  with  such  flexibility  are: 

•  To  allow  SWAN  to  be  used  from  laboratory  conditions  to  shelf  seas  (but  not  harbors, 
see  above); 

•  To  nest  SWAN  in  the  WAM  or  WAVEWATCH  HI  models,  which  are  formulated  in 
terms  of  spherical  coordinates; 

•  These  facilities  are  not  meant  to  support  the  use  of  SWAN  on  oceanic  scales,  however, 
because  the  authors  have  no  ambition  to  apply  SWAN  beyond  coastal  areas.  SWAN  has 
not  been  extensively  tested  on  oceanic  scales  and  is  certainly  less  efficient  than 

WAVEWATCH  IE  or  WAM  on  oceanic  scales  (SWAN  does  not  parallelize  or  vectorize 
well). 
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3.3  Internal  Scenarios,  Limiters,  Shortcomings  and  Coding  Bugs 

User  inputs  may  cause  SWAN  to  produce  unreliable  or  unrealistic  results,  especially  in  cases  where 
the  bathymetry  or  the  wave  field  is  not  well  resolved.  Be  aware  that  the  grid  on  which  the 
computations  are  performed  interpolates  from  the  grids  on  which  the  input  is  provided;  different 
resolutions  for  these  grids  (which  are  allowed)  can  therefore  create  unexpected  interpolation 
patterns  on  the  computational  grid.  In  such  cases  SWAN,  instead  of  terminating  the  computations, 
may  invoke  the  following  internal  scenarios  or  limiters  (see  examples  below).  The  reasons  for  this 
model  policy  are  that  (a)  SWAN  needs  to  be  robust  or  (b)  the  problem  may  be  only  very  local  or  (c) 
the  problem  needs  to  be  computed  through  to  be  diagnosed. 

The  SWAN  user  may  encounter  other  fundamental  shortcomings  and  unintentional  coding  bugs  of 
SWAN,  which  may  or  may  not  be  typical  for  third-generation  wave  models. 

Because  of  these  shortcomings,  the  results  may  look  realistic  but  they  may  (locally)  not  be  accurate. 

Coding  bugs  and  limitations: 

•  The  user  can  request  that  refraction  over  one  spatial  grid  step  is  limited  to  about  90°  (see 
command  NUMERIC,  Section  4.12.10.2).  This  may  be  relevant  when  the  depth  varies 
considerably  over  one  spatial  grid  step  (e.g.  at  the  edge  of  oceans  or  near  oceanic  islands 
with  only  one  or  two  grid  steps  to  go  from  oceanic  depths  to  a  shallow  coast).  This  implies 
inaccurate  refraction  computations  in  such  grid  steps.  This  may  be  acceptable  when 
refraction  has  only  local  effects  that  can  be  ignored  but,  depending  on  the  topography,  the 
(inaccurately  computed)  effects  may  radiate  far  into  the  computational  area. 

•  SWAN  cannot  handle  wave  propagation  on  super-critical  current  flow.  If  such  flow  is 
encountered  during  SWAN  computations,  the  current  is  locally  reduced  to  sub-critical  flow. 

•  If  the  water  depth  is  less  than  some  user-provided  limit,  the  depth  is  set  at  that  limit  (default 
is  0.05  m,  see  command  SET,  Section  4.12.4.2). 

•  SWAN  may  not  reproduce  the  user-imposed  wave  boundary  conditions  as  SWAN  replaces 
the  imposed  waves  that  move  out  of  the  computational  area  at  the  boundaries  with  the 
computed  waves  that  move  out  of  the  computational  area  at  the  boundaries. 

•  SWAN  may  have  convergence  problems.  There  are  three  iteration  processes  in  SWAN: 

a)  An  iteration  process  for  the  spatial  propagation  of  the  waves. 

For  spatial  propagation  the  change  of  the  wave  field  over  one  iteration  is  limited 
to  some  realistic  value  (usually  several  iterations  for  stationary  conditions  or  one 
iteration  or  upgrade  per  time  step  for  non-stationary  conditions  (see  command 
NUMERIC,  Section  4.12.10.2)).  This  is  a  common  problem  for  all  third-generation 
wave  models  that  use  the  DIA  of  the  quadruplet  interactions.  It  does  not  seem  to 
affect  the  result  seriously  in  many  cases  but  sometimes  SWAN  fails  to  converge 
properly  due  to  an  unresolved  bug. 

b)  An  iteration  process  for  spectral  propagation  (current-induced  refraction  and 
frequency  shift)  if  ambient  currents  are  present. 
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For  spectral  propagation  (but  only  current-induced  refraction  and  frequency  shift), 
SWAN  may  not  converge  some  unresolved  bug  in  the  numerical  technique.  (See  the 
SWAN  web  site). 

c)  An  iteration  process  for  solving  the  set-up  equation  if  the  user  requests  wave- 
induced  set-up. 

For  the  wave-induced  set-up,  SWAN  may  not  converge  some  unresolved  bug  in 
the  numerical  technique.  (See  the  SWAN  web  site). 

Information  on  the  actual  convergence  of  a  particular  SWAN  run  is  provided  in  the  PRINT  file 
(available  on  the  SWAN  web  site). 

Any  change  in  these  scenarios,  limiters  or  shortcomings  (in  particular  newly  discovered  coding 
bugs  and  their  fixes)  are  published  on  the  SWAN  web  site  and  implemented  in  new  releases  of 
SWAN  (http://swan.ct.tudelft.nl). 


4.0  Operating  Guidelines 


The  purpose  of  this  section  is  to  give  some  general  advice  in  choosing  the  basic  input  for  SWAN 
computations.  Suggestions  are  given  that  should  help  the  user  to  choose  among  the  many  options 
available  in  SWAN,  such  as  what  physical  processes  to  include  or  exclude,  boundary  conditions, 
and  in  which  mode  or  dimension  to  run  SWAN  (first-,  second-  or  third-generation  mode  and  1-D  or 
2-D). 

An  important  question  addressed  is  how  to  choose  various  grids  in  SWAN  (input,  computation, 
output),  (resolution,  orientation  etc.),  or  nesting  options  (only  for  uniform  rectilinear  grid).  The 
idea  of  nesting  is  to  first  compute  the  waves  on  a  coarse  grid  for  a  larger  region  and  then  on  a  finer 
grid  for  a  smaller  region.  The  computation  on  the  fine  grid  uses  boundary  conditions  that  are 
generated  by  the  computation  on  the  coarse  grid.  Nesting  can  be  repeated  on  ever  decreasing 
scales.  Use  the  same  type  of  coordinates  for  coarse  and  nested  computations  (Cartesian  or 
spherical).  Curvilinear  grids  can  be  used  for  nested  computations  but  the  boundaries  should  always 
be  rectangular. 

It  must  be  pointed  out  that  the  application  of  SWAN  on  ocean  scales  is  not  recommended  from  an 
efficiency  point  of  view.  The  WAM  and  WAVEWATCH  m  models  have  been  designed 
specifically  for  ocean  applications  and  are  probably  one  order  of  magnitude  more  efficient  than 
SWAN  (SWAN  can  be  nested  into  these  models).  SWAN  can  be  run  on  large  scales  (much  larger 
than  coastal  scales)  but  this  option  is  mainly  intended  for  the  transition  from  ocean  scales  to  coastal 
scales  (transitions  where  non-stationary  is  an  issue  and  spherical  coordinates  are  convenient  for 
nesting). 

A  general  suggestion  is  to  start  simple.  SWAN  helps  in  this  with  default  options. 
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4.1  Customizing  SWAN 

Although  SWAN  runs  unaltered  on  almost  any  type  of  computer,  there  may  be  reasons  to  make 
changes  in  the  source  code  before  compilation: 

(A)  Depending  on  the  complexity  of  the  cases  for  which  SWAN  is  used  and  the  computer  memory 
available,  the  size  of  the  dynamic  data  pool  can  be  set  to  another  value.  The  procedure  for  this 
is  explained  in  Section  4.1.1. 

(B)  Some  computer  or  compiler-dependent  Fortran  statements  can  or  need  to  be  activated.  Section 

4.1.2  deals  with  compiler  dependent  statements.  The  compiler  dependent  statements  are 
provided  for  Fortran90  compilers  that  have  been  used  at  Delft  University  of  Technology  (Lahey 
for  Windows  and  Linux,  Absoft  for  MacOS,  MIPSpro  for  SGI-Irix  and  CF90  for  Cray-Unicos). 

(C)  SWAN  also  allows  for  customizing  the  input  and  the  output  to  the  user’s  wishes.  This  either 
can  be  done  permanently  by  changing  several  statements  in  ocpids.for,  as  explained  in  Section 

4.1.3  or  by  changing  the  settings  in  the  file  swaninit,  which  is  created  the  first  time  SWAN  is 
executed  on  a  computer  system.  The  changes  in  swaninit  only  affect  the  runs  executed  in  the 
directory  that  contains  the  modified  swaninit  file.  A  detailed  description  of  the  swaninit  file  is 
given  in  Section  4.2. 


4.1.1  Modifications  in  Pool  Size  (poolcomm.inc) 

The  dynamic  data  pool  stores  all  data  used  in  the  SWAN  calculations  that  are  dependent  on  the  size 
of  the  case  for  which  SWAN  is  used.  The  size  of  the  dynamic  data  pool  is  set  in  one  of  the  include 
files.  In  order  to  enlarge  or  decrease  the  size  of  the  pool,  change  the  number  in  the  statement: 

PARAMETER  (MXPOOL=....). 

This  statement  is  located  in  the  file  poolcomm.inc  at  point  5  of  the  header  (parameter  variables). 

The  size  of  the  pool  is  approximately  the  product  of  the  maximum  number  of  grid  points  that  can  be 
used  in  the  calculations.  Therefore: 

-  In  the  case  of  stationary  calculations:  mxc*myc*msc*mdc. 

-  In  the  case  of  non-stationary  calculations:  2*mxc*myc*msc*mdc. 

-  In  the  case  of  [iquad]  =  3,  add:  mxc*myc*msc*mdc. 

More  detailed  information  regarding  memory  requirements  is  found  in  Section  4.11.3.  Note:  These 
numbers  cost  MXPOOL*4  bytes.  The  default  setting  for  MXPOOL  is  12,500,000,  which  is  the 
recommended  amount  to  run  the  cases  in  the  benchmark  test  for  SWAN.  The  setting  for  MXPOOL 
can  be  changed  according  to  individual  needs  using  the  above  estimates  for  the  required  memory. 
For  field  cases  the  pool-size  is  normally  set  between  20,000,000  and  100,000,000.  SWAN  has  been 
used  with  pool-sizes  up  to  500,000,000  (2  GB  of  memory).  If  you  make  the  pool-size  too  large  (i.e. 
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you  have  limited  memory  in  your  computer  system),  errors  can  result  during  the  compilation  phase. 
If  the  pool  is  too  small,  the  program  will  give  an  indication  of  how  large  it  should  be.  One  can  also 
use  the  POOL  command  in  SWAN  to  get  information  on  the  size  of  the  pool  during  run  time. 


4.1.2  Compiler  Dependent  Statements  (ocpids.for  and  ocpmix.for) 

The  subroutine  OCPINI  (ocpids.for)  and  FOR  (ocpmix.for)  should  be  adapted  when  using  a  Cray  or 
SGI  f90  compiler.  These  compilers  cannot  read/write  lines  longer  than  256  characters  by  default. 
The  option  RECL  =  1000  in  the  OPEN  statement  will  also  allow  these  compilers  to  read/write 
sufficiently  long  lines.  The  appropriate  option  is  indicated  as  follows: 

C/Cray:  Cray  f90  compiler 

C/SGI:  SGI  f90  compiler 

You  should  remove  the  Cl*  code  to  activate  the  commands  for  the  specific  compiler. 


4.1.3  User  Dependent  Modifications  (ocpids.for) 

Subroutine  OCPINI: 

a.  The  integers  INPUTF  and  PRINTF  are  the  unit  reference  numbers  for  the  input  and  print  files. 
On  most  mainframe  computers  they  are  5  and  6,  respectively.  If  necessary,  you  can  change 
these  to  the  standard  input  and  output  unit  numbers  for  your  installation.  Another  unit  reference 
number,  SCREEN,  is  for  output  to  screen.  When  using  a  batch-system,  SCREEN  should  be  set 
equal  to  PRINTF,  as  there  is  no  separate  output  to  screen.  PRTEST  is  a  unit  number  used  for  a 
separate  test  print  file.  In  the  version  that  you  downloaded  from  SWAN’s  ftp  site,  PRTEST  is 
equal  to  PRINTF  so  that  the  test  output  will  appear  on  the  same  file  as  the  standard  print  output. 

b.  The  standard  input  file  and  standard  print  file  are  usually  named  'INPUT'  and  'PRINT', 
respectively  (see  Subroutine  OCPINI).  If  the  users  system  has  problems  with  these  explicit 
OPEN  statements,  please  inform  Delft  University  or  NRL. 

NB  Other  OPEN  statements  appearing  in  SWAN  usually  need  not  be  modified  since  the 
filenames  are  variable. 

c.  TABC  is  the  ASCII  value  for  the  TAB  character.  Change  the  number  9  in  the  assignment 
statement  TABC  =  CHAR(9)  to  the  value  in  the  user’s  ASCII  table  (which  may  be  different 
from  9). 

d.  COMID  is  the  comment  identifier.  It  is  usually  '$',  but  on  some  installations  this  may  be 
inappropriate  because  a  line  beginning  with  $  is  interpreted  as  a  command  for  the  operating 
system  (e.g.  VAX  systems).  If  necessary  change  to  '!'. 
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e.  The  directory  separation  character  varies  depending  on  the  platform  that  is  used  (CHAR(92) 

(=’Y)  on  a  PC;  /  on  a  Unix  system  and  :  on  a  Macintosh).  DIRCH1  indicates  the  separation 
character  that  is  expected  in  the  input  file,  and  DIRCH2  indicates  the  character  that  is  used  on 
the  platform  that  SWAN  is  run  on.  Proper  use  of  this  option  allows  the  sharing  of  input  files 
across  platforms. 

f.  The  character  string,  INST,  contains  the  name  of  the  institute  that  carries  out  the  computations. 

You  can  assign  to  it  the  name  of  your  institute  instead  of  'DELFT  UNIVERSITY  OF 
TECHNOLOGY',  which  is  its  present  value. 

g.  The  type  of  plot  code  is  chosen  by  subroutine  OCPINI  as  well  as  a  number  of  other  parameters. 
These  are  the  same  values  that  will  appear  in  the  file  swaninit  (see  Section  4.2).  The  standard 
plot  code  option  is  HPGL.  There  are  six  significant  plotting  parameters  that  have  the  following 
meaning  for  the  HPGL  option: 

1)  Maximum  size  of  the  figure  frame  in  horizontal  direction 

2)  Maximum  size  of  the  figure  frame  in  vertical  direction 

3)  Conversion  factor  from  cm  to  plotting  units  (plotting  units  per  centimeter) 

4)  Horizontal  margins  in  centimeters 

5)  Vertical  margins  in  centimeters 

6)  Orientation  of  the  paper  (0  =  landscape;  1  =  portrait). 

The  other  possibility  is  called  OPPL  (Ocean  Pack  Plot  code),  which  is  the  same  code  as  used  in 
HISWA.  HISWA  users  who  prefer  to  keep  the  same  type  of  plot  code  should  change  the  word 
HPGL  to  OPPL  in  the  setup  file  or  in  the  source  code. 

NB  The  standard  (default)  paper  format  is  A4.  For  other  (standard)  paper  formats  the  first 
two  parameters  must  be  adjusted. 

h.  There  are  various  options  for  the  shape  of  the  frame  used  in  graphical  output.  If  necessary,  new 
options  can  be  added  in  the  subroutine  OPFRAM,  which  is  also  in  the  file  ocpids.for.  The 
options  include: 

=  2  Full  frame  appears  with  caption  (default), 

=  1  Only  the  frame  appears, 

=  0  No  frame  is  plotted. 

The  file  ocpids.for  contains  a  set  of  basic  plotting  subroutines  with  names  starting  with  OP 
which  can  generate  two  types  of  plot  code:  HPGL  (HP  graphic  language)  or  OPPL  (Ocean  Pack 
Plot  code,  i.e.,  the  same  code  as  produced  by  HISWA).  If  a  user  so  desires  he  can  add  options 
in  each  subroutine  to  generate  another  plot  code.  The  basic  plotting  routines  do  not  send  plot 
instructions  directly  to  the  plotter  but  generate  ASCII  data  in  a  file.  Depending  on  the  plot  code 
used,  a  separate  program  is  needed  to  translate  these  data  into  actual  plot  instructions.  Such  a 
program  is  installation  dependent  and  is  therefore  not  commonly  available  with  the  SWAN 
package. 
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i.  Date  and  time  can  be  read  and  written  according  to  the  various  options  discussed  below. 

Subroutines  DTSTTI  and  DTTIST  are  used  to  convert  a  time  string  to  and  from  numerical  time 
indication.  The  following  options  are  available: 


1  ISO  notation: 

2 

3 

4 

5 

6  (as  in  WAM): 


19870530.153000 
30-May-87  15:30:00 
05/30/87  15:30:00 
15:30:00 

87/05/30  15:30:00 
8705301530 


Suggestions  for  new  options  can  be  made  to  the  SWAN  authors. 

Note:  The  ISO  notation  is  recommended,  as  it  has  no  millennium  problem.  In  all  other  cases 
the  range  of  valid  dates  is  chosen  to  be  between  1  January  191 1  and  31  December  2010  (both 
inclusive). 


4.2  Setup  File  swaninit 

The  standard  version  of  the  setup  file  swaninit  (which  is  generated  the  first  time  that  SWAN  is  run 
after  implementation)  reads: 

Version  of  initialization  file. 

Name  of  institute. 

Command  file  reference  number. 

Command  file  name. 

Print  file  reference  number. 

Print  file  name. 

Test  file  reference  number. 

Test  file  name. 

Screen  reference  number. 

Highest  file  reference  number. 

Comment  identifier. 

TAB  character. 

Dir  sep  character  in  input  file. 

Dir  sep  character  replacing  previous  one. 

Plotting  option  (OPPL,  HPGL,  etc). 

Number  of  plotting  parameters  (Default  values  shown. 
Definition  of  parameters  on  line  1 104  of  ocpids.for). 

0.  0000  0.  0000  0.  0000 

Default  plotting  frame  option. 

Default  time  coding  option, 
in  this  file. 

The  version  number  of  the  initialization  file  is  included  in  the  file  so  that  SWAN  can  verify  whether 

the  file  it  reads  is  a  valid  setup  file.  The  references  to  the  previous  section  (4.1.3),  under  OCPINI  a 
to  g  are: 


2 

Delft  University  of  Technology 

3 

INPUT 

4 

PRINT 

4 

6 

9  9 
$ 

[TAB] 

\ 

\ 

HPGL 

6 

18.  0000  26.  0000  402.  0000 
2 
1 

Use  the  TAB  key  on  your  keyboard  to  insert  [TAB] 
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Name  of  institute: 

see  e. 

The  data  for  command  file,  print  file,  test  file  and  screen: 

see  a  and  b. 

Comment  identifier: 

see  d. 

Tab  character: 

see  c. 

Directory  separation  character: 

see  e. 

Plotting  option  and  plot  parameters: 

see  g. 

Plot  frame: 

see  h. 

Date/time  option: 

see  i. 

4.3  Compiling  SWAN 

After  the  necessary  modifications  are  made  as  described  in  Section  4.1,  the  source  code  is  ready  for 
compilation.  All  source  code  except  the  input  for  test  problems  is  written  in  fixed  form  Fortran90 
so  a  Fortran90  compiler  must  be  available  in  order  to  compile  SWAN.  SWAN  has  been  developed 
with  the  Lahey  F95  compiler  version  5.00  and  for  SGI  workstations,  with  the  f90  compiler  version 
7.30.  On  Unix  (Irix,  Unicos,  Linux,  etc.)  workstations  it  may  be  necessary  to  rename  all  *.for  files 
to  *.f  files.  The  source  code  cannot  be  compiled  with  a  Fortran77  compiler  since  it  contains  several 
Fortran90  features.  The  SWAN  source  code  complies  with  the  ANSI  Fortran90  standard,  except 
for  a  few  cases  where  the  limit  of  19  continuation  lines  is  violated.  The  SWAN  developers  are 
currently  not  aware  of  a  compiler  that  cannot  deal  with  this  violation  of  the  ANSI  standard. 
Furthermore,  the  source  code  contains  one  remaining  computed  goto,  which  is  an  obsolete  feature 
in  Fortran90.  This  should  not  affect  the  compilation  or  the  execution  of  SWAN.  In  the  future, 
SWAN  will  be  rewritten  in  free  form  Fortran90  and  all  CHARACTERS  statements  will  be 
replaced  by  a  CHARACTER(LEN=n)  statement  to  prepare  for  Fortran95. 

When  compiling  SWAN,  check  that  the  compiler  allocates  the  same  amount  of  memory  for  all 
REALS,  INTEGERS  and  LOGICALS.  Normally  four  bytes  are  allocated  for  these  variables. 
Sometimes  on  supercomputers  (vector  or  parallel)  the  memory  is  eight  bytes.  When  a  compiler 
allocates  eight  bytes  for  a  REAL  and  four  bytes  for  an  INTEGER,  for  example,  SWAN  will  not  run 
correctly.  Most  compilers  have  an  option  that  initializes  all  variables  automatically  to  zero.  It  is 
strongly  recommended  to  use  that  option.  There  are  cases  that  cannot  run  correctly  if  this  compiler- 
option  is  not  used.  The  module  swmodl.for  should  be  compiled  first.  Several  subroutines  use  the 
module  contained  in  this  file  and  they  need  a  compiled  version  of  swmodl.for  before  they  can  be 
compiled. 


4.4  Linking  SWAN 

The  following  files  should  be  linked,  in  order  to  get  a  SWAN  executable: 

Object  files  of  the  source  files:  swmodl .for  swanmain.for,  swanprel  .for, 

swanpre2.for,  swancoml.for,  swancom2.for, 
swancom3.for,  swancom4.for,  swancom5.for. 
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The  name  of  the  executable  file  is 
“a.out” 

“swanmain.exe” 


swancomi.for,  swanoutl.for,  swanout2.for, 
swanout3.for,  swanser.for,  ocpids.for,  ocpcre.for, 
ocpdpn.for,  ocplot.for,  ocpmix.for 

for  the  versions  running  under  Unix, 
for  the  PC  version  generated  with  the  Lahey 
Fortran90  compiler  (in  case  swanmain.for  is  first  on 
the  list).  It  is  suggested  that  this  file  be  renamed 
swan.exe. 


4.5  SWAN  Command  File 

The  name  of  the  command  file  should  have  the  extension  .swn. 

•  If  the  name  is  testOl  .swn,  the  DOS  command  to  run  SWAN  with  this  file  is  swan.bat  testOl 
runs  in  a  DOS  box  under  the  WINDOWS  operating  system. 

•  In  this  command  file,  the  user  should  give  the  file  names.  In  the  MS-DOS  operating  system 
these  file  names  consist  of  two  parts,  the  first  of  which  is  at  most  eight  characters  long,  and 
the  second  of  which  is  at  most  three  characters  long.  The  two  parts  are  separated  by  a  dot. 
The  MS-DOS  system  does  not  distinguish  between  lowercase  and  uppercase  characters  in 
filenames. 

•  The  file  swan.bat  should  be  generated  at  the  time  of  installation  of  SWAN  (see  Section 
4.5.1), 

•  The  same  procedure  is  followed  on  other  computers  with  different  operating  systems.  When 
running  under  the  Unix  operating  system  remember  that  filenames  are  case-sensitive  unlike 
those  on  MS-DOS. 

•  The  file  swan.edt  is  available  in  Appendix  C  and  from  the  internet-site  to  assist  in  editing  an 
input  file  for  SWAN. 


4.5.1  Batch  File  and  Unix  Script 


The  run  procedure  for  SWAN  is  dependent  on  the  operating  system.  The  procedure  should  do  the 
following: 

1.  Copy  the  command  file  to  INPUT  (assuming  INPUT  is  the  standard  file  name  for  command 
input,  see  Section  4.1.3b). 

2.  Run  SWAN. 

3.  Copy  the  file  PRINT,  assuming  PRINT  is  the  standard  file  name  for  output.  See  Section 
4.1.3b). 
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Examples  of  such  a  procedure  for  DOS  (file  swan.bat)  or  for  Unix  systems  (file  swan.unx)  are 
given  below. 

Suggested  file  swan.bat  for  DOS: 

echo  off 

if  not  exist  %l.swn  goto  error 

copy  %l.swn  INPUT 

if  exist  Errfile  del  Errfile 

c : . . \swan . exe 

if  exist  %l.prt  del  %l.prt 

ren  PRINT  %l.prt 

if  not  exist  Errfile  goto  finish 
echo  Errors  have  occurred 
type  Errfile 
pause 

goto  finish 
: error 

******************************************************* 

input  file  %l.swn  does  not  exist 
******************************************************* 


: finish 
echo  on 
exit 

The  path  of  the  swan.exe  file  in  this  version  of  the  batch  file  might  have  to  be  adjusted. 

Suggested  script  file  for  Unix  (swan.unx): 

#!/bin/csh 
set  SWAN=/prog 
set  INP=/test 
cp  $INP/$l.swn  INPUT  >nul 
$ SWAN/ swan 

cp  PRINT  $INP/$1 . prt  >nul 
cp  source  $INP/$l.src  >nul 

Some  adjustments  may  be  necessary.  A  similar  procedure  may  be  followed  on  other  operating 
systems. 


echo . 
echo . 
echo. 
* 

echo, 
echo . 

echo 

pause 


4.6  Units  and  Coordinate  Systems 


SWAN  expects  all  quantities  input  by  the  user  to  be  expressed  in  S.I.  units:  m,  kg,  s  and  composites 
of  these  with  accepted  compounds  (such  as  Newton  (N)  and  Watt  (W)).  Consequently  the  wave 
height  and  water  depth  are  in  m,  wave  period  in  s,  etc.  For  wind  and  wave  direction  both  the 
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Cartesian  and  a  Nautical  convention  may  be  used  (see  below).  Directions  and  spherical  coordinates 
are  in  degrees  (°)  and  not  in  radians. 

For  the  output  of  wave  energy  the  user  can  choose  between  variance  (m2)  or  energy  (spatial  density 
in  Joule/m  i.e.,  energy  per  unit  sea  surface)  and  the  equivalents  in  case  of  energy  transport  (m3/s  or 
Watt/m  i.e.,  energy  transport  per  unit  length)  and  spectral  energy  density  (m2s/rad  or  Js/m2/rad  i.e., 
energy  per  unit  frequency  and  direction  per  unit  sea  surface  area).  The  wave-induced  stress 
components  obtained  as  spatial  derivatives  of  wave-induced  radiation  stress  are  always  expressed  in 
N/m  even  if  the  wave  energy  is  in  terms  of  variance.  Note  that  the  energy  density  is  also  in 
Joule/m  in  the  case  of  spherical  coordinates. 

SWAN  operates  either  in  a  Cartesian  coordinate  system  or  in  a  spherical  coordinate  system,  i.e.,  in 
a  flat  plane  or  on  a  spherical  earth.  In  the  Cartesian  system  all  geographic  locations  and 
orientations  in  SWAN,  such  as  for  the  bottom  grid  or  for  output  points,  are  defined  in  one  common 
Cartesian  coordinate  system  with  origin  (0, 0)  by  definition.  The  user  may  choose  this  geographic 
origin  arbitrarily.  This  system  is  designated  in  this  manual  as  the  problem  coordinate  system.  With 
a  spherical  coordinate  system  all  geographic  locations  and  orientations  in  SWAN  are  defined  in 
geographic  longitude  and  latitude.  Both  coordinate  systems  are  designated  in  this  manual  as  the 
problem  coordinate  system. 

In  the  input  and  output  of  SWAN  the  direction  of  wind  and  waves  are  defined  according  to  either 
(a)  the  Cartesian  convention,  which  is  the  direction  of  the  vector  points,  measured  counterclockwise 
from  the  positive  x-axis  of  this  system  (in  degrees)  or  (b)  a  Nautical  convention  which  is  the 
direction  the  wind  or  waves  come  from,  measured  clockwise  from  geographic  North.  All  other 
directions  (such  as  orientation  of  grids)  follow  the  Cartesian  convention. 

For  regular  grids  (i.e.  uniform  and  rectangular).  Figure  4.12-1  in  Section  4.12.6.1  shows  how  the 
locations  of  the  various  grids  are  determined  with  respect  to  the  problem  coordinates.  All  grid 
points  of  a  curvilinear  grid  are  relative  to  the  problem  coordinate  system. 


4.7  Choice  of  Grids,  Time  Windows  and  Boundary  /  Initial  /  First  Guess  Conditions 

Several  types  of  grids  and  time  window(s)  need  to  be  defined:  (a)  spectral  grid,  (b)  spatial 
(geographic)  grids  and  time  window(s)  (for  nonstationary  computations). 

The  spectral  grid  that  needs  to  be  defined  by  the  user  is: 

•  A  computational  spectral  grid  on  which  SWAN  performs  the  computations.  SWAN  has 
the  option  to  make  computations  that  are  nested  in  SWAN,  WAM,  or  WAVEWATCH 
1H).  In  such  cases,  the  nested  spectral  grid  need  not  be  equal  to  the  spectral  grid  in  the 
coarse  model  run. 

The  spatial  grids  that  need  to  be  defined  by  the  user  are  (if  required): 
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•  One  (or  more)  spatial  input  grid(s)  for  the  bottom,  current  field,  water  level,  friction 
coefficient  and  wind  (each  input  grid  may  differ  from  the  others), 

•  A  computational  spatial  grid  on  which  SWAN  performs  the  computations  and, 

•  One  (or  more)  spatial  output  grid(s)  on  which  the  user  requires  output  of  SWAN. 

•  The  winds  and  bottom  friction  do  not  require  a  grid  if  they  are  uniform  over  the  area  of 
interest. 

•  If  a  uniform  and  rectangular  computational  spatial  grid  is  used  in  SWAN  (to  be  decided 
by  the  user),  then  all  input  and  output  grids  should  be  uniform  and  rectangular,  but  they 
may  all  be  different  from  each  other. 

•  If  a  curvilinear  computational  spatial  grid  is  used  in  SWAN  (to  be  decided  by  the  user), 
then  each  input  grid  should  be  (a)  uniform  and  rectangular  (but  not  necessarily  identical 
to  the  other  grids)  or  (b)  identical  to  the  curvilinear  computational  grid  or  staggered  with 
respect  to  the  curvilinear  computational  grid. 

•  Output  grids  used  for  plotting  of  isolines  and  vector  fields  always  need  to  be  uniform 
and  rectangular. 

•  SWAN  has  the  option  to  make  computations  that  are  nested  in  SWAN,  WAM  or 
WAVEWATCH  HI.  In  such  runs,  SWAN  interpolates  the  spatial  boundary  of  the 
SWAN,  WAM  or  WAVEWATCH  HI  grid  to  the  user  provided  grid  of  SWAN  (that 
needs  to  nearly  coincide  along  the  grid  lines  of  WAM,  WAVEWATCH  III,  or  the  output 
nest  grid  boundaries  of  SWAN).  Since  grid  lines  in  WAM  and  WAVEWATCH  HI  are 
in  spherical  coordinates,  it  is  recommended  to  use  spherical  coordinates  in  a  nested 
SWAN  when  nesting  in  WAM  or  WAVEWATCH  IH. 

Similarly,  the  wind  fields  may  be  available  in  different  time  windows  than  the  current  and  water 
level  fields  and  the  computations  may  need  to  be  carried  out  at  other  times  than  these  input  fields. 
For  these  reasons,  SWAN  operates  with  different  time  windows  and  different  time  steps  each 
having  a  different  start  and  end  time  and  time  step: 

•  The  user  gives  one  (or  more)  input  time  window(s)  in  which  the  bottom,  current  field, 
water  level,  friction  coefficient  and  wind  field  (if  present).  Each  input  window  may 
differ  from  the  others, 

•  One  computational  time  window  in  which  SWAN  performs  the  computations,  and 

•  One  (or  more)  output  time  window(s)  in  which  the  user  requires  output  of  SWAN. 

SWAN  has  the  option  to  make  computations  that  are  nested  in  SWAN,  WAM  or  WAVEWATCH 
ITT-  SWAN  searches  the  boundary  conditions  in  the  relevant  output  file  of  the  previous  SWAN, 
WAM  or  WAVEWATCH  IQ  runs  to  take  the  boundary  conditions  at  the  start  time  of  the  nested 
run.  It  will  not  take  the  initial  condition  (i.e.  over  the  entire  computational  grid)  for  the  nested  run 
from  the  previous  SWAN,  WAM  or  WAVEWATCH  m  run. 

During  the  computations  (on  the  computational  grid  and  window)  SWAN  obtains  bottom,  current, 
water  level,  wind  and  bottom  friction  information  by  tri-linear  interpolation  from  the  input  grid(s) 
and  window(s).  The  output  is  in  turn  obtained  in  SWAN  by  bi-linear  interpolation  in  space  from 
the  computational  grid.  There  is  no  interpolation  in  time  for  output  (this  does  not  apply  to  input). 
The  output  time  is  shifted  to  the  nearest  computational  time  level.  The  user  can  reduce 
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interpolation  errors  by  taking  the  grids  and  windows  as  equal  to  one  another  as  possible  (preferably 
identical).  It  is  recommended  to  choose  output  times  such  that  they  coincide  with  computational 
time  levels. 


4.7.1  Input  Grid(s)  and  Time  Window(s) 

The  bathymetry,  current,  water  level,  bottom  friction  and  wind  (if  spatially  variable)  need  to  be 
provided  to  SWAN  on  so-called  input  grids.  It  is  best  to  make  an  input  grid  so  large  that  it 
completely  covers  the  computational  grid. 

In  the  region  outside  the  input  grid,  SWAN  assumes  that  the  bottom  level,  water  level,  and  friction 
coefficient  are  identical  to  those  at  the  nearest  boundary  of  the  input  grid  (lateral  shift  of  that 
boundary).  In  the  regions  not  covered  by  this  lateral  shift  (i.e.  in  the  outside  quadrants  of  the 
comers  of  the  input  grid),  a  constant  field  equal  to  the  value  at  the  nearest  comer  point  of  the  input 
grid  is  taken.  For  the  current  and  wind  velocity  SWAN  takes  0  m/s  for  points  outside  the  input 
grid. 


One  should  choose  the  spatial  resolution  for  the  input  grids  such  that  relevant  spatial  details  in  the 
bathymetry,  currents,  bottom  friction  and  wind  are  properly  resolved.  Special  care  is  required  in 
cases  with  sharp  and  shallow  ridges  (sand  bars,  shoals)  in  the  sea  bottom  and  extremely  steep 
bottom  slopes.  Inaccurate  bathymetry  can  result  in  inaccurate  refraction  computations  that  can 
propagate  into  areas  where  refraction  is  not  significant  (the  results  may  appear  to  be  unstable).  For 
instance,  waves  skirting  an  island  that  is  poorly  resolved  may  propagate  beyond  the  island  with 
entirely  wrong  directions.  In  such  a  case  it  may  even  be  better  to  deactivate  the  refraction 
computations  if  refraction  is  irrelevant  for  the  problem  at  hand.  Such  as  if  the  refracted  waves  will 
run  into  the  coast  anyway.  In  such  cases,  the  ridges  are  vitally  important  to  obtaining  good  SWAN 
results  (at  sea  the  waves  are  clipped  by  depth  induced  breaking  over  the  ridges  and  must  be 
represented  in  SWAN  computation).  This  requires  not  only  that  these  ridges  should  be  well 
represented  on  the  input  grid  and  after  interpolation  on  the  computational  grid.  This  can  be 
achieved  by  choosing  the  grid  lines  of  the  input  grid  along  the  ridges  (even  if  this  may  require  some 
slight  "shifting"  of  the  ridges)  and  by  choosing  the  computational  grid  to  be  identical  to  the  input 
grid.  Otherwise,  the  ridge  may  be  "lost"  in  the  interpolation  from  the  bottom-input  grid  to  the 
computational  grid. 

In  SWAN,  the  bathymetry,  current,  water  level,  wind  and  bottom  friction  may  be  time-varying,  in 
which  case  there  is  a  time  window  associated  with  the  input  (this  need  not  be  identical  with  the 
computational,  output  or  other  input  windows).  It  is  best  to  make  input  windows  such  that  they 
entirely  contain  the  computational  window. 

SWAN  assumes  zero  values  for  input  at  times  before  the  earliest  begin  time  of  the  input  parameters 
(e.g.  wind  speed).  SWAN  assumes  constant  values  (the  last  values)  at  times  after  the  end  time  of 
each  input  parameter. 
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For  input  one  should  use  a  time  step  that  is  small  enough  that  time  variations  in  the  bathymetry, 
current,  water  level,  wind  and  bottom  friction  are  well  resolved. 

Since  the  locations  of  input  and  other  grids  are  formulated  in  terms  of  numbers  instead  of  maps, 
errors  may  easily  occur.  The  PLOTGEO  command  has  options  to  plot  bathymetry  together  with 
locations  of  grids.  This  can  be  used  to  check  the  locations. 

4.7.2  Computational  Grids  and  Boundary  / Initial / First  Guess  Conditions 

The  user  must  choose  the  computational  spatial  grid.  The  orientation  (direction)  can  be  chosen 
arbitrarily. 

The  boundaries  of  the  computational  spatial  grid  in  SWAN  are  either  land  or  water.  With  land 
there  is  no  problem  because  the  land  does  not  generate  waves  and  absorbs  all  incoming  wave 
energy.  Water  boundaries  pose  a  problem,  because  wave  conditions  are  often  unknown  and  SWAN 
assumes  that  no  waves  can  enter  and  exit  the  area  freely.  These  assumptions  obviously  contain 
errors  that  propagate  into  the  model.  Boundaries  must  therefore  be  chosen  far  enough  away  from 
the  area  where  reliable  computations  are  needed  so  as  not  to  affect  the  computational  results.  This 
can  be  established  by  varying  the  location  of  the  boundaries  and  inspecting  the  effect  on  the  results. 
Sometimes  the  waves  at  these  boundaries  can  be  estimated  with  a  certain  degree  of  reliability,  such 
as  when  the  results  of  another  model  run  (nested  computations)  or  observations  are  available.  If 
model  results  are  available  along  the  boundaries  of  the  computational  spatial  grid,  they  are  usually 
from  a  coarser  resolution  than  the  computational  spatial  grid  under  consideration.  The  resolution  of 
the  forcing  will  obviously  have  an  impact  on  the  simulation  and  must  be  chosen  such  that 
variability  of  forcing  is  well  described. 

Non-specification  of  boundary  conditions  is  equivalent  to  specification  of  zero  incident  energy  at 
that  boundary.  This  can  obviously  lead  to  error.  Coarse  specifications  of  incident  energy  (e.g.,  by 
nesting)  is  preferable  to  uniform  specification,  which  is  in  turn  preferable  to  non-specification.  If 
observations  are  available,  they  can  be  used  as  input  at  the  boundaries,  or  some  portion  thereof. 

A  special  case  occurs  near  the  coast,  where  it  is  often  possible  to  identify  an  up-wave  boundary 
(with  proper  wave  information)  and  two  lateral  boundaries  (with  partial  or  no  wave  information). 
The  affected  areas  with  errors  are  typically  regions  with  the  apex  at  the  comers  of  the  water 
boundary  with  wave  information,  spreading  towards  shore  at  an  angle  of  30°  to  45°  for  wind-sea 
conditions  to  either  side  of  the  imposed  mean  wave  direction.  The  angle  is  less  for  swell  conditions 
and  is  essentially  the  one-sided  width  of  the  directional  distribution  of  wave  energy.  For 
propagation  of  short  crested  waves  (wind-sea  conditions)  an  example  is  given  in  Fig.  4.7-1.  For 
this  reason  the  lateral  boundaries  should  be  sufficiently  far  away  from  the  area  of  interest  to  avoid 
the  propagation  of  this  error  into  this  area.  Such  problems  do  not  occur  if  the  lateral  boundaries 
contain  proper  wave  information  over  their  entire  length,  e.g.,  obtained  from  a  previous  SWAN 
computation  or  if  the  lateral  boundaries  are  coast. 
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Fig.  4.7-1.  Disturbed  regions  in  the  computational  grid  due  to  erroneous  boundary  conditions  are  indicated  with  shaded 
areas. 


If  the  computational  grid  extends  outside  the  input  grid,  the  reader  is  referred  to  Section  4.7.1 
(input  grid)  to  find  the  assumptions  of  SWAN  on  depth,  current,  water  level,  wind  and  bottom 
friction  in  the  non-overlapping  area. 

The  spatial  resolution  of  the  computational  grid  should  be  sufficient  to  resolve  relevant  details  of 
the  wave  field.  It  is  usually  a  good  choice  to  take  the  resolution  of  the  computational  grid 
approximately  equal  to  that  of  the  input  (bottom/current)  grid. 


SWAN  may  not  use  the  entire  user-provided  computational  grid  if  the  user  defines  exception  values 
on  the  depth  grid  (see  command  INPGRED,  Section  4.12.7.1)  or  the  computational  grid  (see 
command  CGRID,  Section  4.12.6.1),  In  such  cases,  a  computational  grid  point  is  either: 

•  “wet”  (i.e.  the  grid  point  is  included  in  the  computations  because  it  represents  water;  this 
may  vary  with  time-dependent  or  wave-induced  water  levels), 

•  “dry”  (i.e.  the  grid  point  is  excluded  from  the  computations  because  it  represents  land  which 
may  vary  with  time-dependent  or  wave-induced  water  levels),  or 

•  “exceptional”  (i.e.  the  grid  point  is  permanently  excluded  from  the  computations  because  it 
is  so  defined  by  the  user). 

If  “exceptional”  grid  points  occur  in  the  computational  grid,  then  SWAN  filters  the  entire 
computational  grid  as  follows: 


•  each  grid  line  between  two  adjacent  wet  computational  grid  points  (a  wet  link)  without  an 
adjacent,  parallel  wet  link  is  removed. 
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•  each  wet  computational  grid  point  that  is  linked  to  only  one  other  wet  computational  grid 
point  is  removed, 

•  SWAN  deletes  each  wet  computational  grid  point  that  has  no  wet  links  after  the  first  filter 
(repeated  until  all  such  wet  computational  grid  points  are  removed). 

The  effect  of  this  filter  is  that  if  exception  values  are  used  for  the  depth  grid  or  the  computational 
grid,  one-dimensional  water  features  are  ignored  in  the  SWAN  computations  (results  at  these 
locations  with  a  width  of  about  one  grid  step  would  be  unrealistic  anyway).  This  is  obvious  in  the 
output  of  SWAN,  as  there  are  no  results  on  these  features  that  are  visible  in  relevant  plots.  It  must 
be  noted  that  the  actual  code  in  SWAN  does  not  use  the  above  procedure  but  another  with  the  same 
effect.  If  no  exception  values  are  used,  this  filter  is  not  applied  because  one-dimensional  features 
may  appear  or  disappear  due  to  changing  water  levels  (flooding  may  create  them,  or  drying  may 
reduce  two-dimensional  features  to  one-dimensional  features). 

When  output  is  requested  along  a  boundary  of  the  computational  grid  it  may  differ  from  the 
boundary  conditions  that  are  imposed  by  the  user.  The  reason  is  that  SWAN  accepts  only  the  user- 
imposed  incoming  wave  components  and  replaces  the  user-imposed  outgoing  components  with 
computed  outgoing  components  (propagating  to  the  boundary  from  the  interior  region).  Moreover, 
SWAN  has  an  option  to  only  compute  within  a  pre-set  directional  sector  (pre-set  by  the  user). 

Wave  components  outside  this  sector  are  totally  ignored  by  SWAN  (with  no  replacements).  The 
user  is  informed  by  means  of  a  WARNING  in  the  output  print  file.  See  Section  4.9  when  the 
computed  significant  wave  height  differs  by  more  than  10%  (the  default)  from  the  user-imposed 
significant  wave  height  (see  commands  BOUND...,  Section  4.12.8).  The  user  can  set  the  actual 
value  of  this  difference  (see  command  SET,  Section  4.12.4.2). 

The  user  must  choose  the  computational  window  in  time.  If  the  initial  condition  is  not  well 
prescribed  by  the  user  (e.g.,  a  user  typically  indicates  a  zero-state  or  parameterized  initial 
condition),  the  computational  window  should  start  early  enough  so  that  the  initial  state  of  SWAN 
has  propagated  through  the  computational  area.  Note  that  a  stationary  computation  can  precede  a 
nonstationary  computation  in  a  single  SWAN  simulation  (i.e.  a  single  command  file  with  multiple 
“COMP”  lines.  See  below).  This  is  sometimes  done  in  order  to  create  a  more  realistic  initial 
condition  for  the  nonstationary  computation. 

The  user  should  give  the  computational  time  step.  Since  SWAN  is  based  on  implicit  numerical 
schemes,  it  is  not  limited  by  the  Courant  stability  criterion  (which  couples  time  and  space  steps).  In 
this  sense,  the  time  step  in  SWAN  is  unlimited.  However,  the  accuracy  of  the  results  of  SWAN  is 
obviously  affected  by  the  time  step.  Generally  the  time  step  in  SWAN  should  be  small  enough  to 
resolve  the  time  variations  of  the  computed  wave  field  itself.  Usually,  it  is  enough  to  consider  the 
time  variations  of  the  driving  fields  (wind,  currents,  water  depth,  wave  boundary  conditions),  but  be 
careful.  Relatively  small  time  variations  in  depth  (e.g.  by  tide)  can  result  in  relatively  large 
variations  in  the  wave  field.  At  the  same  time,  a  large  Courant  number  (»  1)  will  lead  to  increased 
numerical  error  (especially  true  if  using  the  S&L  scheme). 
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The  first  guess  conditions  of  a  stationary  run  of  SWAN  are  default  determined  with  the  2n<^ 
generation  mode  of  SWAN.  The  initial  condition  of  a  nonstationary  run  of  SWAN  is  by  default  a 
JONSWAP  spectrum  with  a  directional  distribution  centered  around  the  local  wind  direction. 

The  user  must  provide  the  computational  spectral  grid.  In  frequency  space  it  is  defined  by  a 
minimum  and  maximum  frequency  and  the  frequency  resolution,  which  is  proportional  to  the 
frequency  itself  (e.g.  A f-  0.1/).  In  the  frequency  domain  the  lowest  frequency  [fl],  the  highest 
frequency  [fh]  and  the  number  of  frequencies  [nfreq]  must  be  chosen  (see  command  CGRDD, 
Section  4.12.6.1).  The  value  of  [fl]  must  be  somewhat  smaller  than  0.7  times  the  value  of  the 
lowest  peak  frequency  expected.  The  value  of  [fh]  must  be  at  least  2.5  to  3  times  the  highest  peak 
frequency  expected;  usually  [fh]  is  chosen  less  than  or  equal  to  1  Hz. 

SWAN  has  the  option  to  make  computations  that  are  nested  in  WAM  or  WAVEWATCH  ID.  In 
such  runs  SWAN  interpolates  the  spectral  grid  of  WAM  or  WAVEWATCH  III  to  the  (user 
provided)  spectral  grid  of  SWAN.  The  WAM  Cycle  4  source  term  in  SWAN  has  been  returned  for 
a  highest  prognostic  frequency  (explicitly  computed  by  SWAN)  of  1  Hz.  It  is  therefore 
recommended  that  for  cases  where  wind  generation  is  important  and  WAM  Cycle  4  formulations 
are  chosen,  the  highest  prognostic  frequency  be  1  Hz.  WAM  Cycle  4  is  not  usually  recommended. 
In  directional  space  the  directional  range  is  the  full  360°  unless  the  user  specifies  a  limited 
directional  range.  This  may  be  more  efficient  (requiring  less  computer  time  and/or  space)  when 
waves  travel  toward  a  coast  within  a  limited  sector  of  180°.  The  number  of  discrete  directions  that 
is  provided  by  the  user  determines  the  directional  resolution.  For  wind  seas  with  a  directional 
spreading  of  typically  30°  on  either  side  of  the  mean  wave  direction,  a  resolution  of  10°  is 
sufficient,  whereas  for  swell  with  a  directional  spreading  of  less  than  10°,  a  resolution  of  2°  or  less 
may  be  required.  If  the  user  is  confident  that  no  energy  will  occur  outside  a  certain  directional 
sector  (or  is  willing  to  ignore  this  energy),  then  the  computations  by  SWAN  can  be  limited  to  the 
directional  sector  that  does  contain  energy.  This  may  often  be  the  case  when  waves  propagate  to 
shore  within  a  sector  of  180°  around  some  mean  wave  direction. 

Use  the  following  discretization  in  SWAN  for  applications  in  coastal  areas: 


Table  4.7-1.  Discretization  in  SWAN. 


Direction  resolution: 
Wind  sea  conditions: 

A0 

15°  -  10° 

Swell  conditions 

A0 

= 

5° -2° 

Frequency  range: 

f  . 

Amin 

— 

0.04  Hz 

f 

Amax 

— 

1.00  Hz 

Spatial  resolution: 

(  A  v  A  i  A 

Ax,  Ay 

- 

50-  1000  m 

The  numerical  schemes  in  the  SWAN  model  require  a  minimum  number  of  two  discrete  grid  points 
in  each  spatial  direction.  If  the  ILU-CGSTAB  solver  is  used  (see  command  NUMERIC,  Section 
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4.12.10.2),  then  the  minimum  number  of  directional  bins  is  three  per  directional  quadrant  and  the 
minimum  number  of  frequencies  will  be  four. 

Interpolation  of  spectra 

The  interpolation  of  spectra  in  SWAN,  both  in  space  and  time,  is  a  slight  modification  of  the 
procedure  used  in  WAM.  This  procedure  is  not  a  simple  (spectral)  bin-by-bin  interpolation  because 
that  would  cause  reduction  of  the  spectral  peak  if  the  peaks  of  the  original  spectra  do  not  coincide. 

It  is  an  interpolation  where  the  spectra  are  first  normalized  by  average  frequency  and  direction  then 
interpolated  and  then  transformed  back. 

The  average  frequencies  of  the  two  origin  spectra  are  determined  using  the  frequency  moments  of 
the  spectra: 

mik  =  JX(<7,0)<7kdcrd0 , 

with  i  =  l,2  (the  two  origin  spectra)  and  k  =  0, 1  (the  zero-  and  first  frequency  moments  of  these 
spectra).  Then 

o  =  X  /  mi  0 . 

The  average  frequency  for  the  interpolated  spectrum  is  calculated  as 
a  =  (wlm11  +  w2m2  l)/(w]mi  0  +  w2m20), 

where  wi  is  the  relative  distance  (in  space  or  time)  from  the  interpolated  spectrum  to  the  first  origin 
spectrum  0)  and  w2  is  the  same  for  the  second  origin  spectrum  A2(er,  0).  Therefore, 

W1+W2  =  1  • 

The  average  directions  of  the  two  origin  spectra  are  determined  using  directional  moments  of  the 
spectra: 

mix  =  JiV,  (<7, 0)cos(0)d<7  cB  and 
miy  =  jX  (er,  0)sin(0)Jrr  J0 , 

with  i  =  l,2.  The  average  direction  is  then 
0;  =  a  tan (mi  y  /  mi  x ) . 

The  average  direction  of  the  interpolated  spectrum  is  calculated  as 
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Gj  =  a  tan[(w,ml  v  +  w2m2  y) /(wtml  x  +  w2m2x). 

Finally  the  interpolated  spectrum  is  calculated  as  follows: 

0)  =  w, TV,  [a, cr  /  a, 0  -  (0  -  0, )]  +  w2  N2  [a2 a /  a, 0  -  (0  -  02 )] . 


4.7.3  Output  Grids 


SWAN  can  provide  output  on  uniform,  rectilinear  spatial  grids  that  are  independent  of  the  input 
grids  and  of  the  computational  grid.  In  a  computation  with  a  curvilinear  computational  grid, 
curvilinear  output  grids  are  available  in  SWAN  but  not  for  isoline  or  vector  plots.  An  output  grid 
must  be  specified  by  the  user,  but  it  is  wise  to  choose  a  resolution  that  is  fine  enough  to  show 
relevant  spatial  details.  It  must  be  pointed  out  that  the  information  on  an  output  grid  is  obtained 
from  the  computational  grid  through  bilinear  interpolation  (output  always  at  computational  time 
level).  This  implies  that  some  inaccuracies  are  introduced  by  this  interpolation.  It  also  implies  that 
bottom  or  current  information  on  a  (output)  plot  has  been  obtained  by  interpolating  twice:  once 
from  the  input  grid  to  the  computational  grid  and  once  from  the  computational  grid  to  the  output 
grid.  If  the  input,  computational  and  output  grids  are  identical,  then  no  interpolation  errors  occur. 

In  the  regions  where  the  output  grid  does  not  cover  the  computational  grid  SWAN  assumes  output 
values  equal  to  the  exception  value;  e.g.  for  Hs  the  exception  value  is  -9.  The  exception  values  of 
output  quantities  can  be  changed  by  means  of  the  QUANTITY  command  (see  Section  4.13.2.1). 

The  user  may  reproduce  the  input  fields  (bathymetry  etc.)  with  commands  FRAME  and  PLOT... 
(See  Sections  4.13.1.1  and  4.13.2). 

In  nonstationary  computations  output  can  be  requested  at  regular  intervals  beginning  with  a  given 
time  and  always  at  computational  times. 

4.8  Activating  Physical  Processes 


SWAN  contains  a  number  of  physical  processes  (see  Section  5.0)  that  add  or  subtract  wave  energy 
to  or  from  the  wave  field.  The  processes  included  are  wind  growth,  whitecapping,  bottom  friction, 
depth-induced  wave  breaking,  obstacle  transmission,  nonlinear  wave-wave  interactions 
(quadruplets  and  triads)  and  wave-induced  set-up.  SWAN  can  run  in  several  modes,  indicating  the 
level  of  parameterization. 


Wind  growth* 

Activated 

Whitecapping* 

Activated 

Quadruplets* 

Activated 

Triads 

Activated 

Bottom  friction 

Activated 

Depth-induced  breaking* 

Activated 

by  commands  GEN  1 ,  GEN2  or  GEN3*. 
by  commands  GEN1,  GEN2  or  GEN3*. 
by  command  GEN3*. 
by  command  TRIAD, 
by  command  FRICTION, 
by  command  BREAKING*. 


24 


SWAN  User’s  Manual 


Obstacle  transmission  Activated  by  command  OBSTACLES. 

Wave-induced  set-up  Activated  by  command  SETUP. 

*  Active  by  default,  can  be  deactivated  with  command  OFF. 

For  the  first  SWAN  runs,  it  is  strongly  advised  to  use  the  default  values  of  the  model  coefficients. 
First  it  should  be  determined  whether  or  not  a  certain  physical  process  is  relevant  to  the  result.  If 
this  cannot  be  decided  by  means  of  a  simple  hand  computation,  one  can  perform  a  SWAN 
computation  with  and  without  the  physical  process  included  in  the  computations,  using  the  standard 
values  chosen  in  SWAN. 

After  it  has  been  established  that  a  certain  physical  process  is  important,  it  may  be  worthwhile  to 
modify  coefficients.  In  the  case  of  wind  growth  one  may  at  first  try  to  vary  the  wind  velocity.  In 
the  bottom  friction  the  best  coefficient  to  vary  is  the  friction  coefficient.  Switching  off  the  depth- 
induced  breaking  term  is  usually  unwise,  since  ii  leads  to  unacceptably  high  wave  heights  near 
beaches  (the  computed  wave  heights  'explode'  due  to  shoaling  effects). 


4.9  Print  file  and  error  messages 

SWAN  always  creates  a  print  file.  The  filename  is  usually  identical  to  the  name  of  the  command 
file  of  the  computations,  with  the  extension  (.SWN)  replaced  with  (.PRT).  Otherwise,  the  filename 
depends  on  the  user’s  batch  file. 

The  print  file  contains  an  echo  of  the  command  file  and  error  messages.  These  messages  are 
usually  self-explanatory.  If  more  assistance  is  required,  users  may  address  the  SWAN  discussion 
group  on  the  SWAN  homepage  (http://swan.ct.tudelft.nl).  Active  WISE  members  may  contact  the 
authors  of  SWAN  for  assistance.  The  print  file  also  contains  computational  results  if  the  user 
requests  them  with  either  command  BLOCK  or  command  TABLE. 


4.10  The  Millennium  Problem 

SWAN  can  run  in  the  nonstationary  mode  for  dates  between  the  years  0  and  9999  if  ISO-notation  is 
used  in  the  input  (recommended),  or  between  the  years  1911  and  2010  if  two-digit  code  for  years  is 
used  (formats  2-6  in  every  command  that  contains  moments  in  time). 

Be  careful  when  nesting  SWAN  in  WAM,  as  WAM  does  not  use  ISO-notation. 
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4.11  Input  /  Output  and  Storage 
4.11.1  General 


SWAN  is  one  single  computer  program,  consisting  of  one  executable  file  (e.g.,  swan.exe),  a 
command  file  (e.g.  a  file  named  “INPUT”  or  a  file  with  extension  .swn,  see  swan.edt.  Appendix  C), 
and  a  run  file  (swan.bat  or  swan.unix).  The  names  of  the  files  provided  by  the  user  should  comply 
with  the  rules  of  file  identification  of  the  computer  system  on  which  SWAN  is  run  (see  Section 
4.12.3).  In  addition,  SWAN  does  not  permit  file  names  longer  than  36  characters.  Moreover,  the 
maximum  length  of  the  lines  in  the  input  files  for  SWAN  is  120  positions. 

The  user  should  provide  SWAN  with  the  following  input  information: 

•  A  command  file  containing  the  user  selected  instructions  to  run  SWAN, 

•  File(s)  containing  bottom,  current,  friction,  and  wind  (if  relevant), 

•  File(s)  containing  the  wave  field  at  the  model  boundaries  (if  relevant). 

The  input  and  output  to  a  number  of  test  problems  is  provided  on  the  SWAN  internet-site  in  the  test 
subdirectory.  The  files  with  extension  .swn  are  the  command  files  for  these  tests.  The  files  with 
extension  .bot  are  the  bottom  files  for  these  tests.  These  files  can  be  used  to  make  a  configuration 
test  of  SWAN  one’s  computer.  Compare  the  results  with  those  in  the  test  documentation.  Note: 
The  results  need  not  be  identical  up  to  the  last  digit.  In  some  test  cases  SWAN  may  generate  an 
error  message  concerning  the  size  of  the  data  pool.  It  explains  how  large  the  pool  actually  is  and 
how  large  it  should  be  for  this  calculation.  There  are  two  solutions  to  this  problem,  either  enlarge 
the  pool  or  reduce  the  grid  resolution(s). 


4.11.2  Input  /  Output  Facilities 

To  assist  in  making  the  command  file,  an  edit  file  is  available  to  the  user  (swan.edt;  see  Appendix 
C).  In  its  original  form  this  file  consists  only  of  comments.  In  the  edit  file  all  commands  in  this 
user’s  manual  are  reproduced  as  a  mnemonic  for  making  the  actual  command  file,  so  a  user  does 
not  need  to  consult  the  user’s  manual  every  time  to  check  the  correct  spelling  of  keywords,  the 
order  of  data,  etc.  The  user  is  advised  to  copy  the  swan.edt  file  (the  copy  file  should  have  a 
different  name)  and  then  type  in  commands  between  the  comment  lines  of  the  edit  file. 

SWAN  is  fairly  flexible  with  regards  to  output.  Output  is  available  for  many  different  wave  and 
wave-related  parameters  such  as  wave-induced  stresses  or  bottom  orbital  motion).  However, 
SWAN  produces  output  only  at  the  user’s  request.  The  instructions  for  controlling  output  are 
separated  into  four  categories: 
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•  Definitions  of  the  geographic  location(s)  of  the  output.  Output  locations  may  be  either  on  a 
regular  geographic  grid,  or  along  user  specified  lines  (e.g.  a  given  depth  contour  line)  or  at 
individual  output  locations. 

•  Times  for  which  this  output  is  requested  (only  in  nonstationary  runs). 

•  Type  of  output  quantity  such  as  waves,  currents,  etc. 

•  Medium  to  which  output  should  be  transferred  (plot  or  disk). 

Plot  output  is  quick-look  output  only,  used  to  show  spatial  variations  of  bottom,  current  or  wave 
related  parameters  in  rectangular  geographic  output  regions  and  spectra  in  individual  geographic 
points. 

This  information  (and  much  more)  is  available  in  data  files. 


4.11.2.1  Output  Files 

SWAN  will  generate  a  number  of  output  files: 

•  Print  Files:  Error  messages  appear  in  a  file  with  the  name  PRINT,  which  can  be  renamed  by 
the  user  with  a  batch  (DOS)  or  script  (Unix)  command.  In  the  DOS  batch  file  and  the  Unix 
script  on  the  SWAN  web  site  the  file  PRINT  is  renamed  to  the  name  of  the  command  file, 
with  the  extension  .swn  replaced  by  .prt.  Files  with  extension  .prt  are  also  referred  to  as 
print  files. 

SWAN  always  creates  a  print  file.  Usually  the  name  of  this  file  is  identical  to  the  name  of 
the  command  file  of  the  computations  with  the  extension  (.swn)  replaced  with  (.prt). 
Otherwise,  it  depends  on  the  user’s  batch  file. 

The  print  file  contains  an  echo  of  the  command  file  and  error  messages  as  well  as 
computational  results  if  the  user  so  requests  (with  command  BLOCK  or  TABLE  (see 
Sections  4.13.2.2  and  4.13.2.3)).  These  messages  are  usually  self-explanatory  (If  not,  active 
WISE  members  can  contact  the  authors  of  SWAN).  Other  users  should  address  the 
discussion  group  on  the  SWAN  web  site). 

•  Numerical  Output:  Output  from  commands  such  as  BLOCK  and  TABLE  appears  in  files 
with  user  provided  names. 

•  Plot  Files:  the  PLOT. . .  commands  generates  one  or  more  plot  files.  If  the  user  does  not 
specify  a  filename  the  plot  file  has  the  name  PLF...,  where  the  run  number  as  defined  in  the 
command  PROJECT  as  NR  appears  on  the  dots. 

•  Error  Files:  A  file  called  Errfile  containing  the  error  messages  is  created  only  when  SWAN 
produces  error  messages.  Existence  of  this  file  is  an  indication  that  results  must  be  carefully 
examined. 
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•  Grid  Point  Error  Files:  A  file  called  ERRPTS  containing  the  grid-points,  where  specific 
errors  occurred  during  the  calculation,  such  as  non-convergence  of  the  iterative  matrix- 
solver.  Existence  of  this  file  is  an  indication  to  study  that  grid-point  spectrum  more 
carefully. 


4.11.3  Storage  Requirements 

The  core  memory  for  SWAN  is  determined  at  the  installation  of  SWAN  on  the  user’s  computer 
system.  Reinstalling  SWAN  with  another  size  of  core  memory  can  change  it.  The  user  cannot  altar 
the  size  of  this  memory  but  considering  the  choice  for  the  computation  of  the  nonlinear  four  wave- 
wave  interactions  can  influence  the  efficiency  of  using  it.  Calculating  these  interactions  per  sweep, 
instead  of  per  iteration,  decreases  the  amount  of  required  memory  by  a  factor  of  2/3  (see  Section 
5.0  and  command  GEN3,  Section  4.12.9.3),  but  increases  the  computing  time.  Calculation  per 
sweep  is  the  default  in  SWAN. 

Only  when  SWAN  is  given  a  task  that  exceeds  the  available  primary  storage  should  the  user 
attempt  to  use  the  available  storage  more  efficiently.  The  largest  of  these  requirements  determines 
whether  SWAN  can  carry  out  a  task  within  the  available  space  or  not. 

The  required  storage  capacity  in  SWAN  depends  on  the  number  of  grid  points  in  x-  and  y-direction 
(mxc*myc)  and  the  number  of  points  in  frequency  and  directional  space  (msc*mdc).  Another 
important  restriction  is  given  by  the  way  the  nonlinear  four  wave-wave  interactions  are  calculated. 

A  rough  estimate  of  the  required  storage  capacity  is  given  in  Tables  4.11-1  and  4.11-2  below. 

Note:  The  required  storage  is  primarily  determined  by  four-dimensional  arrays  (e  g  A1  (x  y  <j,  9) 
A,+1  (x,  y,  tr,  9)). 


Table  4.11-1.  Estimate  of  required  storage  capacity  of  SWAN  for  Stationary  Run  (with  default  SORDUP  scheme),  or 
Stationary  or  Nonstationary  Runs  (with  BSBT  scheme  with  one  update  of  the  wave  field  per  time  step). 


Required  memory 
floating  point  numbers 
single  nrecision 

Spectra: 

mxc*myc*msc*mdc 

Quadruplet  interaction: 

Fully  explicit 

iquad  in  command  GEN3 

add 

negligible 

360°-sector 

add 

mxc*myc*msc*mdc 

Semi-implicit 

90°-sector 

add 

negligible 
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Table  4.11-2.  Estimate  of  required  storage  capacity  of  SWAN  for  Nonstationary  Run  (with  default  S&L  scheme  or  with 
BSBT). 


Required  memory 
floating  point  numbers 
single  precision 


Spectra: 

2*mxc*myc*msc*mdc 

Quadruplet  interaction: 

Fully  explicit 

[iquad]  =  2 

add 

negligible 

[iquad]  =  3 

add 

mxc*myc*msc*mdc 

Semi-implicit 

[iquad]  =  1 

add 

negligible 

The  value  of  [iquad]  refers  to  implicit  or  explicit  computations  of  the  quadruplet  wave-wave 
interactions  (see  command  GEN3,  Section  4.12.9.3,  default  [iquad]  =  2).  Some  additional  arrays 
are  used  for  the  bottom,  current,  wind,  wave  number,  different  propagation  velocities  and  some 
auxiliary  arrays,  however,  these  are  negligible  compared  to  the  rather  large  four-dimensional  arrays 
mxc*myc*msc*mdc. 


4.12  Description  of  Commands 
4.12.1  List  of  A  vailable  Commands 

The  following  commands  are  available  to  SWAN  users. 

Start-up  commands  (Section  4.12.4) 

Block  (a) 

PROJECT  Title  of  the  problem  to  be  computed. 

SET  Sets  values  of  certain  general  parameters. 

MODE  Requests  a  stationary  /  nonstationary  or  1  D-mode  /  2D-mode  of 

SWAN. 

COORD  For  choosing  between  Cartesian  and  spherical  coordinates. 

General  commands  (Section  4.12.5) 

Block  (b) 

TEST  Requests  the  output  of  intermediate  results  for  testing  purposes. 

POOL  Requests  status  of  computer  memory. 

Model  Description  Commands  (Section  4.12.6) 

Block  (c) 

Computational  grid  commands  (Section  4.12.6.1) 

CGRID  Defines  dimension  of  computational  grid. 

READGRID  Reads  a  curvilinear  computational  grid. 


Block  (d) 

Input  field  commands  (Section  4.12.7) 
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INPGRID 

READINP 

WIND 


Defines  dimension  of  bottom  grid,  etc. 
Reads  input  fields. 

Activates  constant  wind  option. 
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Block  (e) 

Boundary/initial  conditions  (Section  4.12.8) 

BOUND...  Defines  boundary  conditions  for  the  computational  spatial  grid. 

BOUNDPAR1 
BOUNDPAR2 
BOUNDSPEC 
BOUNDNEST1 
BOUNDNEST2 
BOUNDNEST3 

INITIAL  Initializes  the  wave  field  for  a  computation. 

Block  (f) 

Physics  commands  (Section 
GEN 


BREAKING 
FRICTION 
TRIAD 
OBSTACLE 
SETUP 
OFF 

Block  (g) 

Numerics  commands  (Section  4.12.10) 

PROP  To  choose  the  numerical  propagation  scheme. 

NUMERIC  Sets  some  of  the  numerical  properties  of  SWAN 


4.12.9) 

SWAN  first-,  second-  or  third-generation  physics. 
GEN1  SWAN  runs  in  first-generation  mode. 
GEN2  SWAN  runs  in  second-generation  mode. 
GEN3  SWAN  runs  in  third-generation  mode. 
Activates  dissipation  by  depth-induced  wave  breaking. 
Activates  dissipation  by  bottom  friction. 

Activates  three  wave-wave  interactions. 

Defines  characteristics  of  sub-grid  obstacles. 

Activates  the  computation  of  the  wave-induced  set-up. 
Deactivates  certain  physical  processes. 


Output  commands  (Section  4.13) 

Block  (h) 

Output  location  commands  (Section  4.13.1) 


FRAME 

GROUP 

CURVE 

RAY 

ISOLINE 

POINTS 

NGRID 

LINE 

SITES 


Defines  an  output  frame  (a  regular  grid). 

Defines  an  output  group  (for  regular  and  curvilinear  grids). 
Defines  an  output  curve. 

Defines  a  set  of  straight  output  lines  (rays). 

Defines  a  depth  or  bottom  contour  for  output  along  that  contour. 
Defines  a  set  of  individual  output  points. 

Defines  a  nested  grid. 

Defines  a  set  of  lines  in  plots. 

Defines  a  set  of  place  names  in  plots. 
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Block  (i) 


Commands  to  write  or  plot  output  quantities  (Section  4.13.2) 


QUANTITY 

BLOCK 

TABLE 

SPECOUT 

NESTOUT 

PLOT... 


Defines  properties  of  output  quantities. 

Requests  a  block  output  (geographic  distribution). 

Requests  writing  of  a  table  (set  of  locations). 

Requests  spectral  output. 

Requests  spectral  output  for  subsequent  nested  computations. 
Requests  plotting  of  a  figure. 


PLOTGEOGR 

PLOTSTAR 

PLOTPP 

PLOTSPEC 


Compute,  hotfile  and  stop  commands  (Section  4.13.3) 

Block  (j) 

Compute,  hotfile  and  stop  commands 

COMPUTE  Starts  a  computation. 

HOTFILE  Stores  results  for  subsequent  SWAN  run. 

STOP  End  of  user's  input. 


4.12.2  Command  Sequence 

SWAN  executes  the  above  command  blocks  (a,...,j)  in  the  above  sequence  except  (b),  (g)  and  (j). 
The  commands  of  the  blocks  (b)  and  (g)  may  appear  anywhere  before  block  (j),  except  that  TEST 
POINTS  must  come  after  READJNP  BOTTOM.  The  commands  of  block  (j)  may  appear  anywhere 
in  the  command  file  (all  commands  after  COMPUTE  are  ignored  by  SWAN,  except  HOTFILE  and 
STOP).  A  sequence  of  blocks  (h)  is  permitted  (all  commands  will  be  executed,  without  overriding). 
Also  a  sequence  of  blocks  such  as  (i)  is  permitted  (all  commands  will  be  executed,  without 
overriding).  Within  the  blocks  the  following  sequence  is  to  be  used: 


In  block  (a): 

No  prescribed  sequence  in  block. 

In  block  (b): 

No  prescribed  sequence  in  block. 

In  block  (c): 

READGRID  after  CGRID. 

In  block  (d): 

READINP  after  INPGRID  (repeat  both  in  this  sequence  for  each 
quantity). 

In  block  (e): 

BOUNDPAR1  before  BOUNDPAR2,  otherwise  no  prescribed 
sequence  in  block. 

In  block  (f): 

Use  only  one  GEN  command  in  command  file.  Use  command  OFF 
only  after  a  GEN  command  (note  that  GEN3  is  default). 

In  block  (g): 

No  prescribed  sequence  in  block. 

In  block  (h): 

ISOLINE  after  RAY  (ISOLINE  and  RAY  can  be  repeated 
independently). 

In  block  (i): 

No  prescribed  sequence  in  block. 
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In  block  (j):  HOTFILE  immediately  after  COMPUTE,  STOP  after  COMPUTE. 

Note:  A  repetition  of  a  command  may  override  an  earlier  occurrence  of  that  command.  Many 
commands  provide  the  user  with  the  opportunity  to  assign  values  to  coefficients  of  SWAN  (e.g.  the 
bottom  friction  coefficient).  If  the  user  does  not  select  such  an  option,  SWAN  will  use  a  default 
value.  Some  commands  cannot  be  used  in  1-D  mode  (see  individual  command  descriptions  below). 

4.12.3  Command  Syntax  and  Input  and  Output  Limitations 

The  command  syntax  is  given  in  Appendix  A. 

Rules  of  file  identification: 

•  The  maximum  length  of  the  input  lines  is  120  characters. 

•  The  maximum  length  of  the  file  names  is  36  characters. 

•  The  maximum  length  of  the  plot  titles  is  36  characters. 

•  The  maximum  number  of  file  names  is  79.  This  can  be  extended  (edit  the  file  swaninit  to 
change  highest  unit  number  from  99  to  a  higher  number). 

•  The  maximum  number  of  plot  files  is  20.  This  can  be  extended  (edit  the  file  ocpids.for). 
This  does  not  limit  the  number  of  plots,  as  a  large  number  of  plots  can  reside  in  one  plot 
file. 


4.12.4  Start-up  Commands 
4.12.4.1  PROJECT 


PROJECT  'name' 
'title  1' 
'titled 
'title3' 


The  PROJ  command  requires  the  user  to  define  a  number  of  strings  to  identify  the  SWAN  run 
(project  name  e.g.,  an  engineering  project)  in  the  print  and  plot  files. 

'name'  Name  of  the  project,  at  most  16  characters  long. 

Default:  blanks. 

nr'  Run  identification  (to  be  provided  as  a  character  string;  e.g.  the  run  number) 

to  distinguish  a  run  from  other  runs  for  the  same  project.  It  is  at  most  four 
characters  long.  It  is  the  only  required  information  in  this  command. 

titlel '  String  of  at  most  72  characters  provided  by  the  user  to  appear  in  the  output  of 
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the  program  for  the  user's  convenience. 
Default:  blanks. 

'title2'  Same  as 'titlel'. 

'title3 '  Same  as  'title  1’. 


4.12.4.2  SET 


SET  [level]  [nor]  [depmin]  [maxmes]  [maxerr]  [grav]  [rho]  & 

|  NAUTICAL  | 

[inrhog]  [hsrerr]  <  >  [pwtail]  [froudmax]  [printf]  [prtest] 

|  ->  CARTESIAN  | 


With  this  optional  command  the  user  assigns  values  to  various  general  parameters. 


[level] 


[nor] 


[depmin] 


[maxmes] 


[maxerr] 


Increase  the  water  level  that  is  constant  in  space  and  time,  [level]  is  the 
value  of  this  increase  (in  m).  For  a  variable  water  level,  reference  is  made 
to  the  commands  INPGRID  and  READINP  (See  Sections  4.12.7.1  and 
4.12.7.2).  Default:  [level]  =  0. 

Direction  of  north  with  respect  to  the  x-axis  (measured  counter-clockwise); 
Default  [nor]  =  90,  i.e.,  the  x-axis  of  the  problem  coordinate  system  points 
east.  When  spherical  coordinates  are  used  (see  command  COORD, 

Section  4.12.4.4)  the  value  of  [nor]  may  not  be  modified. 

Threshold  depth  (in  m).  In  the  computation,  any  positive  depth  smaller 
than  [depmin]  is  made  equal  to  [depmin].  Default:  [depmin]  =  0.05. 

Maximum  number  of  error  messages  incurred  (not  necessarily  the  number 
of  errors!)  during  the  computation  beyond  which  the  computation  is 
terminated.  During  the  computational  process  messages  are  written  to  the 
print  file,  e.g.,  if  the  action  density  or  the  frequency  in  a  point  becomes 
negative.  Such  negative  values  are  a  sign  that  instabilities  may  have 
occurred).  Default:  [maxmes]  =  200. 

Note:  When  a  number  [maxmes]  of  error  messages,  have  been  written  to 
the  PRT  file  (see  Section  4.9),  the  computation  will  stop.  If  necessary 
make  [maxmes]  larger  using  command  SET,  and  rerun  the  program. 

SWAN  checks  input  data  during  pre-processing.  Depending  on  the 
severity  of  the  errors  encountered,  SWAN  does  not  start  computations. 

The  user  can  influence  the  error  level  above  which  SWAN  will  not  start 
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[grav] 

[rho] 

[inrhog] 

[hsrerr] 

NAUTICAL 

CARTESIAN 

[pwtail] 


computations  (the  computations  will  continue  at  the  level  indicated).  The 
error  level  [maxerr]  is  coded  as  follows: 

=  1  Warnings; 

=  2  Errors  (possibly  automatically  repaired  or  repairable  by  SWAN); 

=  3  Severe  errors. 

Default:  [maxerr]  =  1 . 

Gravitational  acceleration  (in  m/s2). 

Default:  [grav]  =  9.81. 

Water  density  (in  kg/m3). 

Default:  [rho]  =  1025. 

Indicates  whether  the  user  requires  output  based  on  variance  or  based  on 
true  energy  (See  Section  4.6). 

=  0  Output  based  on  variance; 

=  1  Output  based  on  true  energy. 

Default:  [inrhog]  =  0. 

Relative  difference  between  the  user-imposed  significant  wave  height  and 
the  significant  wave  height  computed  by  SWAN  (anywhere  along  the 
computational  grid  boundary)  above  which  a  WARNING  will  be  given. 
This  relative  difference  normalized  with  the  user-provided  significant  wave 
height.  This  warning  will  be  given  for  each  boundary  grid  point  where  the 
problem  occurs  along  with  the  x-  and  y-index  number  of  the  computational 
grid  (See  Section  4.13.2),  To  suppress  these  warnings  (in  particular  for 
nonstationary  computations),  set  [hsrerr]  at  a  vei^  high  value  or  use 
command  OFF  BNDCHK. 


Indicates  that  the  Nautical  convention  for  wind  and  wave  direction  (SWAN 
input  and  output)  will  be  used  instead  of  the  default  Cartesian  convention. 
(For  definition  see  Section  4.6). 

Indicates  that  the  Cartesian  convention  for  wind  and  wave  direction 
(SWAN  input  and  output)  will  be  used.  (For  definition  see  Section  4.6). 

Power  of  high  frequency  tail.  Defines  the  shape  of  the  spectral  tail  above 
the  highest  prognostic  frequency  [fhigh]  (see  command  CGRID,  Section 
4.12.6.1),  The  energy  density  is  assumed  to  be  proportional  to  frequency 
to  the  power  [pwtail].  Default  values  depend  on  formulations  of  physics: 
command  GEN  1,  [pwtail]  =  5 

command  GEN2,  [pwtail]  =  5 

command  GEN 3  KOMEN,  [pwtail]  =  4 

command  GEN3  JANSEN,  [pwtail]  =  5 

If  the  user  wishes  to  use  another  value,  then  this  SET  command  should  be 


34 


SWAN  User’s  Manual 


located  in  the  command  file  after  the  GEN1,  GEN  2  or  GEN3  command 
(these  will  otherwise  override  the  SET  command  as  regards  [pwtail]). 

[printf]  Unit  reference  number  of  the  print  file.  Initially  [printf]  is  equal  to  four.  If 

it  is  changed  to  six,  all  print  output  would  be  written  to  the  screen.  This  is 
useful  if  print  output  is  lost  due  to  an  abnormal  end  of  the  program  and 
information  about  the  reason  will  print  to  file. 

[prtest]  Unit  reference  number  of  the  test  output  file.  Initially  [prtest]  is  equal  to 

four.  If  it  is  changed  to  six,  all  test  output  will  be  written  to  the  screen. 
This  is  useful  if  test  print  output  is  lost  due  to  abnormal  end  of  the 
program,  and  information  about  the  reason  should  appear  in  the  test  print 
file. 


4.12.4.3  MODE 


|  ->  STATIONARY  | 

MODE  <  >  & 

|  NONSTATIONARY  | 

|  ->  TWODIMENSIONAL  | 

<  > 

|  ONEDIMENSIONAL  | 


With  this  optional  command  the  user  selects  that  the  SWAN  run  be  either  stationary  or 
nonstationary  and  one-dimensional  (1-D  mode)  or  two-dimensional  (2-D  mode).  Selecting 
nonstationary  allows  for  the  following  (see  command  COMPUTE,  Section  4.13.3.1): 

•  one  nonstationary  computation, 

•  a  sequence  of  stationary  computations, 

•  a  mix  of  (a)  and  (b). 

The  default  option  of  MODE  is  STATIONARY  TWODIMENSIONAL. 

4.12.4.4  COORDINATES 


| ->  CARTESIAN  | 

COORDINATES  <  )  ->  CCM 1  >  REPEATING 

|  SPHERICAL  <  >  | 
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I  QC  | 


The  command  COORDINATES  allows  for  choosing  between  Cartesian  and  spherical  coordinates. 
A  nested  SWAN  run  must  use  the  same  coordinate  system  as  the  coarse  grid  SWAN  run. 


CARTESIAN 


All  locations  and  distances  are  in  m.  Coordinates  are  given  with  respect 
to  x-and  y-axes  chosen  by  the  user  in  the  various  commands. 


SPHERICAL 


CCM 


All  coordinates  of  locations  and  geographical  grid  sizes  are  given  in 
degrees.  The  variable  x  is  longitude,  x  =  0  is  the  Greenwich  meridian  and 
x  >  0  is  east  of  this  meridian.  The  variable  y  is  latitude,  y  >  0  is  the 
Northern  Hemisphere.  Input  and  output  grids  must  be  oriented  with  their 
x-axes  to  the  east.  Mesh  sizes  are  in  degrees.  All  other  distances  are  in  m. 

The  Central  Conformal  Mercator  projection.  This  command  defines  the 
projection  method  in  case  of  spherical  coordinates.  The  horizontal  and 
vertical  scales  are  uniform  over  the  area  shown,  measured  in  terms  of 
cm/degree.  The  center  (and  only  the  center)  of  the  scale  is  identical  to  that 
of  the  conventional  Mercator  projection.  The  area  in  the  projection  center 
is  therefore  exactly  conformal. 


QC  Quasi-Cartesian  project  method,  where  the  horizontal  and  vertical  scales 

are  equal  to  one  another  in  terms  of  cm/degree. 

Note:  SPHERICAL  coordinates  may  also  be  used  for  relatively  small  areas,  say  10  or  20  km 
horizontal  dimension.  This  may  be  useful  if  one  obtains  the  boundary  conditions  by  nesting  in  an 
oceanic  model  that  is  naturally  formulated  in  spherical  coordinates. 


Also  note  that  for  spherical  coordinates  regular  grids  must  always  be  oriented  E-W,  N-S,  using 

[alpc]  =  0,  [alpinp]  =  0,  [alpfr]  =  0  (see  commands  CGRID,  INPUT  GRID,  and  FRAME  Sections 
4.12.6.1, 4.12.7.1  and  4.13.1.1). 


4.12.5 

General  Commands 

4.12.5.1 

TEST 

TEST 

[itest]  [itracel  POINTS 

|->U  <[i]  (j]  >  | 

<  > 

1  XY<[x][y]  >  | 

& 

(PAR  'fname')  (S 1 D  'fname') 

(S2D  'fname'i 
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If  SWAN  produces  unexpected  results,  this  optional  command  can  be  used  to  instruct  the  program 
to  produce  intermediate  results  during  a  SWAN  run  (test  output).  A  TEST  command  may  alternate 
between  commands  in  the  file  during  the  execution  to  change  the  level  of  test  output  during  a 
SWAN  run.  A  TEST  command  controls  the  test  output  until  the  next  TEST  command.  Subsequent 
TEST  commands  may  have  a  level  0,  which  will  suppress  the  test  output. 

[itest]  The  level  of  test  output.  For  values  under  100  the  amount  is  usually 

reasonable,  for  values  above  200  it  can  be  very  large.  For  values  of  [itest] 
up  to  50  the  user  can  interpret  the  test  output.  Higher  values  of  [itest]  result 
in  output  that  can  only  be  interpreted  by  those  who  have  the  program  source 
listing  at  their  disposal.  Default:  [itest]  =  30 

[itrace]  SWAN  writes  a  message  (name  of  subroutine)  to  the  print  file  at  the  first 

[itrace]  entries  of  each  subroutine.  Default:  [itrace]  =  0 

POINTS  Produces  a  detailed  print  out  during  the  model  run  for  a  grid  point  on  the 

computational  grid.  Output  at  a  maximum  of  50  grid  points  is  possible. 

This  option  can  be  used  only  after  the  bathymetry  has  been  read  (See 
command  READINP  BOTTOM,  Section  4.12.7.2). 

U  The  test  points  are  defined  by  means  of  grid  indices. 

[i],  [j]  Grid  indices  of  a  test  point.  Values  of  [i]  range  between  0  and  [mxc]  (See 

command  CGRID,  Section  4.12.6.1),  values  of  [j]  between  0  and  [myc] 
(inclusive). 

The  test  points  are  defined  in  terms  of  problem  coordinates.  SWAN  will 
determine  the  nearest  grid  points.  Output  will  be  made  for  this  selected  grid 
point. 

Coordinates  of  a  test  point.  Problem  coordinates  (in  meters  (m))  for 
Cartesian  coordinates,  or  longitude  and  latitude  (in  degrees)  for  spherical 
coordinates.  See  command  COORD,  Section  4.12.4.4), 

PAR  Integral  parameters  for  test  points.  These  are  written:  HSIGN,  TM01,  (for 

definitions  see  Section  4.14)  and  Swind,  Swcap,  Ssurf,  Sfric,  Snl3  and 
Snl4,  which  are  the  integrals  over  frequency  and  direction  of  the  respective 
source  terms  of  wind  input,  whitecapping,  depth-induced  breaking,  bottom 
friction,  absolute  value  of  the  triad  wave-wave  interactions,  and  absolute 
value  of  the  quadruplet  wave-wave  interactions. 

SID  If  the  keyword  SID  appears  variance  densities  and  six  source  terms*  will  be 

printed  as  1-D  spectral  (frequency)  output.  The  file  definition  is  given  in 


XY 

[x],  [y] 
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Appendix  D.  The  output  will  be  made  after  every  iteration  for  MODE 
STATIONARY  and  after  every  time  step  for  MODE  NONSTATIONARY 
(see  command  MODE,  Section  4.12.4.3), 

'fname'  Name  of  the  file  to  which  the  output  is  written. 

Default:  fname  =  SWSRC1D. 

S2D  If  the  keyword  S2D  appears,  variance  densities  and  six  source  terms*  as 

computed  will  be  printed  as  2-D  (frequency  and  direction)  spectral  output. 
The  file  description  is  given  in  Appendix  D.  The  output  will  be  made  after 
every  iteration  for  MODE  STATIONARY  and  after  every  time  step  for 
MODE  NONSTATIONARY  (see  command  MODE,  Section  4.12.4.3), 

'fname'  Name  of  the  file  to  which  the  output  is  written.  Default:  fname  = 

SWSRC2D. 

*  The  source  terms  written  due  to  the  presence  of  the  keyword  SID  or  S2D  are  source  terms  of 
variance  density.  The  six  source  terms  are:  wind  input,  whitecapping,  bottom  friction,  breaking,  3- 
wave  interactions  and  4-wave  interactions. 

4.12.5.2  POOL 
POOL 


This  optional  command  can  be  used  to  obtain  information  on  the  numerical  data  pool,  which 
contains  almost  all  numerical  data  in  SWAN.  The  program  will  answer  by  providing  the  amount  of 
data  in  use  when  the  POOL  command  is  received  by  the  program,  the  amount  of  data  expected  to  be 
needed  later  in  the  run,  and  the  actual  size  of  the  pool,  which  is  determined  at  the  implementation  of 
the  program;  expressed  in  number  of  reals,  number  of  bytes  =  reals  x  4  or  reals  x  8.  An  example  of 
the  output  follows: 

Data  pool  size  defined  at  installation: 

Occupied  memory  after  executing  last  command  before  this  instance  of  POOL: 

Estimated  additional  memory  needed  after  this  instance  of  POOL: 

TOTAL  estimated  memory  for  this  run: 


2000000 

425230 

125906 

551136 


4.12.6  Computational  Grid  Commands 


4.12.6.1  CGRID 


|  ->  REGULAR  [xpc]  fypc]  [alpc]  [xlenc]  [ylenc]  [mxc]  [myc]  I 
CGRID  <  > 

|  CURVILINEAR  [mxc]  [myc]  (EXCEPTION  [xexc]  [yexc])| 
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I  ->  CIRCLE  | 

<  >  [mdc]  [flow]  [fhigh]  [msc] 

|  SECTOR  [dirl]  [dir2]  | 


This  required  command  allows  the  user  to  define  the  geographic  location,  size,  resolution  and 
orientation  of  the  computational  grid  in  the  problem  coordinate  system  (see  Section  4.7.2)  for  a 
uniform,  rectilinear  computational  grid  or  to  define  the  size  of  a  curvilinear  grid  (see  Section  4.6). 
The  origin  of  the  grid  and  the  direction  of  the  positive  x-axis  may  be  chosen  arbitrarily  by  the  user. 
CGRID  must  be  used  for  nested  runs  and  for  a  nested  run  the  geographic  and  spectral  range 
(directional  sector  inclusive)  and  resolution  may  differ  from  the  previous  run  (zeros  are  used 
outside  these  ranges). 

REGULAR  This  option  indicates  that  the  computational  grid  is  to  be  taken  as  uniform  and 

rectangular. 

CURVILINEAR  This  option  indicates  that  the  computational  grid  is  to  be  taken  as  curvilinear. 

The  user  must  provide  the  coordinates  of  the  grid  points  with  command 
READGRID. 

[xpc]  Geographic  location  of  the  origin  of  the  computational  grid  in  the  problem 

coordinate  system  (x-coordinate,  in  m).  (See  command  COORD,  Section 
4.12.4.4),  Default:  [xpc]  =  0.0 

[ypc]  Geographic  location  of  the  origin  of  the  computational  grid  in  the  problem 

coordinate  system  (y-coordinate,  in  m).  (See  command  COORD,  Section 
4.12.4.4),  Default:  [ypc]  =  0.0 

[alpc]  Direction  of  the  positive  x-axis  of  the  computational  grid  in  degrees 

(Cartesian  convention).  In  1-D  mode,  [alpc]  should  be  equal  to  the  direction 
[alpinp]  (see  command  INPGRID,  Section  4.12.7.1).  Default:  [alpc]  =  0.0 

[xlenc]  Length  of  the  computational  grid  in  x-direction  (in  m).  For  spherical 

coordinates  [xlenc]  is  in  degrees. 

[ylenc]  Length  of  the  computational  grid  in  y-direction  (in  m).  In  1-D  mode,  [ylenc] 

=  0.  For  spherical  coordinates,  [ylenc]  is  in  degrees. 

[mxc]  Number  of  meshes  in  computational  grid  in  x-direction  for  a  uniform, 

rectilinear  grid  or  x*-direction  for  a  curvilinear  grid  (this  number  is  one  less 
than  the  number  of  grid  points  in  this  domain),  i.e..  Ax  =  [xclen]/[mxc]  for  a 
uniform,  rectilinear  grid. 

[myc]  Number  of  meshes  in  computational  grid  in  y-direction  for  a  uniform, 

rectilinear  grid  or  y*-direction  for  a  curvilinear  grid  (this  number  is  one  less 
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EXCEPTION 


[xexc] 


[yexc] 


CIRCLE 


than  the  number  of  grid  points  in  this  domain),  i.e.,  Ay  =  [yclen]/[myc]  for  a 
uniform,  rectilinear  grid.  In  1-D  mode,  [myc]  should  be  [myc]  =  0. 

Only  available  in  the  case  of  a  curvilinear  grid.  If  certain  grid  points  are  to  be 
ignored  during  the  computations,  such  as  land  points  that  remain  dry,  (no 
flooding),  thus  saving  computer  time  and  memory,  then  this  can  be  indicated 
by  identifying  the  grid  points  in  the  file  that  contain  the  grid  point 
coordinates.  (See  command  READGRID,  Section  4.12.6.2  and  as  an 
alternative  see  command  INPGRID  BOTTOM,  Section  4.12.7.1). 

Indicates  that  a  grid  point  is  to  be  ignored  in  the  computations.  This  value  is 
provided  by  the  user  at  the  location  of  the  x-coordinate  considered  in  the  file 
of  the  x-coordinates;  see  command  READGRID,  Section  4.12.6.2.  The  value 
is  required  if  EXCEPTION  is  used. 

Indicates  that  a  grid  point  is  to  be  ignored  in  the  computation.  This  value  is 
provided  by  the  user  at  the  location  of  the  y-coordinate  considered  in  the  file 
of  the  y-coordinates;  see  command  READGRID,  Section  4.12.6.2,  The  value 
is  required  if  EXCEPTION  is  used.  Default:  [yexc]  =  [xexc]. 

Indicates  that  the  spectral  directions  cover  the  full  circle.  This  option  is 
default. 


SECTOR 


fdirl) 

[dir2] 

[mdc] 


Allows  for  only  spectral  wave  directions  in  a  limited  directional  sector  to  be 
considered.  The  range  of  this  sector  is  given  by  [dirl]  and  [dir2].  If  the 
quadruplet  interactions  are  to  be  computed  (see  command  GEN3,  Section 
4.12.9.3),  then  SECTOR  should  be  30°  wider  on  each  side  than  the  directional 
sector  occupied  by  the  spectrum  (everywhere  in  the  computational  grid).  If 
not,  then  these  computations  will  be  inaccurate.  If  the  directional  distribution 
of  the  spectrum  is  symmetric  around  the  center  of  the  SECTOR,  then  the 
computed  quadruplet  wave-wave  interactions  are  effectively  zero  in  the  30° 
range  on  either  end  of  the  SECTOR.  The  problem  can  be  avoided  by  not 
activating  the  quadruplet  wave-wave  interactions  (use  command  GEN1  or 
GEN2)  or,  if  activated  (with  command  GEN3),  by  subsequently  de-activating 
them  with  command  OFF  QUAD. 

The  direction  of  the  right-hand  boundary  of  the  sector  when  looking  outward 
from  the  sector  (required  for  option  SECTOR)  in  degrees. 

The  direction  of  the  left-hand  boundary  of  the  sector  when  looking  outward 
from  the  sector  (required  for  option  SECTOR)  in  degrees. 

Number  of  meshes  in  0-space.  For  CIRCLE,  this  is  the  number  of 
subdivisions  of  the  360  degrees  of  a  circle,  so  A0  =  [360°]/[mdc]  is  the 
spectral  directional  resolution.  In  the  case  of  SECTOR  A0  =  { [dir2]  - 
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[flow] 

[fhigh] 

[msc] 


[dirl]  }/[mdc].  If  the  ILU-CGSTAB  solver  is  used  (see  command  NUMERIC, 
Section  4.12.10.2),  then  the  minimum  number  of  directional  bins  is  three  per 
directional  quadrant. 

Lowest  discrete  frequency  that  is  used  in  the  calculation  (in  Hz). 

Highest  discrete  frequency  that  is  used  in  the  calculation  (in  Hz). 

One  less  than  the  number  of  frequencies.  This  defines  the  grid  resolution  in 
frequency-space  between  the  lowest  discrete  frequency  [flow]  and  the  highest 
discrete  frequency  [fhigh].  This  resolution  is  not  constant,  since  the 
frequencies  are  distributed  logarithmically:  f,+i  =  y  fj ,  where  y  is  a  constant. 
The  value  of  [msc]  depends  on  the  frequency  resolution,  A f  which  the  user 
requires.  Since  the  frequency  distribution  on  the  frequency  axis  is 
logarithmic,  the  relationship  is: 


A/: 


/ r  n  •  _  J.r\/[msc] 


[Jhighl 

[flow] 


-1 


/ 


Conversely,  if  the  user  chooses  the  value  of  A/ / /,  then  the  value  of  [nfreq]  is 
given  by: 

If  the  ILU-CGSTAB  solver  is  used  (see  command  NUMERIC,  Section 
4.12.10.2)  then  the  minimum  number  of  frequencies  is  four.  It  must  be 
observed  that  the  DIA  of  the  quadruplet  interactions  is  based  on  a  frequency 
resolution  of  Af/f  =  0. 1 .  The  actual  resolution  in  the  computations  should 
therefore  not  deviate  too  much  from  this. 


For  illustration  of  the  quantities  [xpc],  [ypc]  and  [alpc]  see  Fig.  4.12-1  below. 


41 


SWAN  User’s  Manual 


Fig.  4.12-1.  Coordinates  of  the  origin  [xpc]  and  [ypc],  the  orientation  [alpc],  and  the  grid  point  numbering  of  the 

computational  grid  with  respect  to  the  problem  coordinates  system.  Note  that  in  case  of  spherical  coordinates  the  xc- 
and  xp-axes  both  point  east. 

4.12.6.2  READGRID  COORDINATES 


READGRID  COORDINATES  [fac]  'fname'  [idla]  [nhedf]  [nhedvec]  & 

|  ->  FREE  | 

!  i 

I  | 'form'  |  j 

<  FORMAT  <  >  > 

I  I  [idfm]  |  | 

!  i 

|  UNFORMATTED 


READGRID  COORDINATES  requires  that  the  user  control  the  reading  of  the  coordinates  of  the 
computational  grid  points.  These  coordinates  must  be  read  from  a  file  as  a  vector  (x-component,  y- 
component  =  x-coordinate,  y-coordinate  of  each  single  grid  point).  READGRID  must  follow  a  ’ 
command  CGRID  CURVILINEAR.  READGRID  COORDINATES  is  required  if  the  computational 
grid  is  curvilinear  but  not  allowed  for  a  regular  grid.  See  command  READINP  in  Section  4.12.7.2 
for  the  description  of  the  READGRID  options.  READGRID  cannot  be  used  in  1-D  mode. 


4.12.7  Input  Grids  and  Data  Commands 

4.12.7.1  INPGRID 

I  bottom  I 
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INPGRID 


WLEVEL 


I  CURRENT 

ivx 

|VY 


(< 


FRICTION 


>) 


& 


|WIND 

IWX 
I WY 


->  REGULAR  [xpinp]  [ypinp]  [alpinp]  [mxinp]  [myinp]  [dxinp]  [dyinp] 


< 

>& 

|  CURVILINEAR  [stagrxl  [stagry]  [mxinp]  [myinp] 

1 

(EXCEPTION  [excval]) 

& 

1 

->  SEC  | 

(NONSTATIONARY  [tbeginp]  [deltinpl  < 

MIN  >  [tendinp]) 

1 

HR  | 

1 

DAY  1 

OPTION  CURVILINEAR  IS  NOT  FOR  1-D  MODE. 

INPGRID  is  a  required  command  in  which  the  user  defines  the  geographic  location,  size  and 
orientation  of  an  input  grid  as  well  as  the  time  characteristics  of  the  variable  if  it  is  not  stationary. 
Non-stationary  variables  should  be  given  in  a  sequence  of  fields,  one  for  each  time  step.  The  actual 
reading  of  bottom  level  values,  currents,  etc.,  from  the  file  is  controlled  by  the  command 
READINP.  INPGRID  must  precede  READINP. 

Grids  may  vary  for  bottom  level  (BOTTOM),  current  (CURRENT),  bottom  friction  coefficient 
(FRICTION)  and  wind  velocity  (WIND).  If  the  current  velocity  components  are  available  on 
different  grids,  then  option  VX,  VY  can  define  these  different  grids  for  the  x-  and  y-component  of 
the  current  (the  grids  must  have  identical  orientation).  Different  grids  for  VX  and  VY  may  be 
useful  if  a  current  model  using  a  staggered  grid  generates  the  data.  The  same  holds  true  for  wind 
velocity  components.  If  INPGRID  is  given  without  any  of  the  keywords  BOTTOM,  WIND  etc.  it  is 
assumed  that  all  the  input  grids  are  the  same. 

The  current  and  wind  vectors  are  defined  with  the  x-  and  y-component  of  the  current  or  wind  vector 
with  respect  to  the  x-axis  of  the  input  grid.  For  wind  velocity  and  friction  coefficient  it  is  also 
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possible  to  use  a  constant  value  over  the  computational  field  (see  commands  WIND  and 
FRICTION,  Sections  4.12.7.3  and  4.12.9.5),  No  grid  definition  for  wind  and  friction  is  required. 

See  Section  4.7  for  more  information  on  grids. 


BOTTOM 

WLEV 

CURRENT 

VX 

VY 

FRICTION 

WIND 

WX 

WY 

REGULAR 


Defines  the  input  grid  of  the  bottom  level.  (For  the  definition  of  the 
bottom  level  see  command  READINP,  Section  4.12.7.2), 

Water  level  relative  to  datum  level,  positive  upward  (in  m). 

Defines  the  input  grid  of  the  current  field  (same  grid  for  x-  and  y- 
components). 

Defines  the  input  grid  of  the  x-component  of  the  current  field 
(different  grid  than  y-component  but  same  orientation). 

Defines  input  grid  of  the  y-component  of  the  current  field  (different 
grid  than  x-component  but  same  orientation). 

Defines  input  grid  of  the  bottom  friction  coefficient  (defined  in 
command  FRICTION,  not  to  be  confused  with  this  option 
FRICTION). 

Defines  input  grid  of  the  wind  field  (same  grid  for  x-  and  y- 
component).  If  neither  of  the  commands  WEND  and  READINP 
WIND  is  used  it  is  assumed  that  there  is  no  wind. 

Defines  input  grid  of  the  x-component  of  the  wind  field  (different  grid 
than  x-component  but  same  orientation). 

Defines  input  grid  of  the  y-component  of  the  wind  field  (different  grid 
than  y-component  but  same  orientation). 

Means  that  the  input  grid  is  regular,  rectangular. 


CURVILINEAR  Means  that  the  input  grid  is  curvilinear;  this  option  is  available  only  if 

the  computational  grid  is  curvilinear  as  well.  The  input  grid  is 
identical  (which  is  default)  to  the  computational  grid,  or  it  is  staggered 
in  x-  and/or  y-direction.  NOT  for  1-D  mode. 


For  a  REGULAR  grid: 

txPinP]  Geographic  location  (x-coordinate)  of  the  origin  of  the  input  grid  in 

problem  coordinates  in  meters  if  Cartesian  coordinates  are  used  and 
degrees  if  spherical  coordinates  are  used,  (see  command  COORD, 
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Section  4.12.4.4).  Default:  [xpinp]  =  0. 

[ypinp]  Geographic  location  (y-coordinate)  of  the  origin  of  the  input  grid  in 

problem  coordinates  in  meters  if  Cartesian  coordinates  are  used  and 
degrees  if  spherical  coordinates  are  used,  (see  command  COORD, 
Section  4.12.4.4).  Default:  [ypinp]  =  0. 

[alpinp]  Direction  of  the  positive  x-axis  of  the  input  grid  (in  degrees,  Cartesian 

convention).  (Section  4.12.4.4).  Default:  [alpinp]  =  0. 

[mxinp]  Number  of  meshes  in  x-direction  of  the  input  grid  (this  number  is  one 

less  than  the  number  of  grid  points  in  this  direction). 

[myinp]  Number  of  meshes  in  y-direction  of  the  input  grid  (this  number  is  one 

less  than  the  number  of  grid  points  in  this  direction).  In  1-D  mode, 
[myinp]  should  be  set  equal  to  zero. 


[dxinp]  Mesh  size  in  x-direction  of  the  input  grid,  in  meters  for  Cartesian 

coordinates,  and  degrees  if  spherical  coordinates  are  used,  (see 
command  COORD,  Section  4.12.4.4), 

[dyinp]  Mesh  size  in  y-direction  of  the  input  grid,  in  meters  for  Cartesian 

coordinates  and  degrees  if  spherical  coordinates  are  used,  (see  command 
COORD,  Section  4.12.4.4).  In  1-D  mode,  [dyinp]  may  have  any  value. 
Default:  [dyinp]  =  [dxinp]. 

For  a  CURVILINEAR  input,  which  has  not  been  fully  tested  for  spherical  coordinates: 

[mxinp]  Number  of  meshes  in  x'-direction  of  the  input  grid  (one  less  than  the 

number  of  grid  points  in  this  direction).  Default:  [mxinp]  =  [mxc]. 

[myinp]  Number  of  meshes  in  y'-direction  of  the  input  grid  (one  less  than  the 

number  of  grid  points  in  this  direction).  Default:  [myinp]  =  [myc]. 

[stagrx]  Staggered  x'-direction  with  respect  to  computational  grid.  Default:  0. 

Note:  e.g.  [stagrx]  =  0.5  means  that  the  grid  points  are  shifted  a  half  step 
in  x'-direction;  in  many  flow  models  x-velocities  are  defined  in  points 
shifted  a  half  step  in  x'-direction. 

[stagry]  Staggered  in  y'-direction  with  respect  to  computational  grid.  Default: 

[stagry]  =  0. 

Note:  e.g.,  [stagry]  =  0.5  means  that  the  grid  points  are  shifted  a  half 
step  in  y'-direction;  in  many  flow  models  y-velocities  are  defined  in 
points  shifted  a  half  step  in  y'-direction. 
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EXCEPTION 

[excval] 

NONSTATIONARY 

[tbeginp] 

[deltinp] 

SEC 

MIN 

HR 

DAY 

[tendinp] 


If  land  points  remain  dry  during  the  computations  (no  flooding),  then 
these  points  can  be  ignored  (saving  computer  time  and  memory)  by 
giving  bottom  level  values  equal  to  [excval]  in  these  grid  points.  NOT 
for  1  -D  mode. 

Exception  value,  which  is  required  if  EXCEPTION  is  used  (see 
command  EXCEPTION). 

The  variable  (given  in  a  time  sequence  of  fields)  is  nonstationary.  NOT 
for  1  -D  mode. 

Begin  time  of  the  first  field  of  the  variable.  The  format  is: 


=  1 

ISO  notation 

19870530.153000 

=  2 

(as  in  HP  compiler): 

'30-May-87  15:30:00’ 

=  3 

(as  in  Lahey  compiler): 

05/30/87.15:30:00 

=  4 

15:30:00 

=  5 

87/05/30  15:30:00’ 

=  6 

as  in  WAM 

8705301530 

This  format  is  installation  dependent.  Refer  to  the  installation  manual 
on  the  SWAN  web  site.  Default  is  ISO. 

Time  interval  between  fields.  The  unit  is  indicated  in  the  next  option. 
Unit  seconds. 

Unit  minutes. 

Unit  hours. 

Unit  days. 

End  time  of  the  last  field  of  the  variable.  The  format  is: 


=  1 

ISO  notation 

19870530.153000 

=  2 

(as  in  HP  compiler): 

'30-May-87  15:30:00’ 

II  II  II 
U  A  w 

(as  in  Lahey  compiler): 

05/30/87.15:30:00 

15:30:00 

'87/05/30  15:30:00’ 

=  6 

as  in  WAM 

8705301530 

This  format  is  installation  dependent.  Refer  to  the  installation  manual 
on  the  SWAN  web  site.  Default  is  ISO. 
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4.12.7.2  READINP 


I  BOTTOM 

I 

I WLEVEL 

I 

1  CURRENT 

I 

READINP  <  WIND 

I 

|  FRICTION 


|  'fnamel'  | 

>  [fac]  <  >  [idla]  & 

|  SERIES  'fname2'  | 

|  ->  FREE 


|  | 'form'  |  | 

[nhedf]  ([nhedt])  ([nhedvec])  <  FORMAT  <  >  > 

I  I  [idfm]  |  | 

I  I 

|  UNFORMATTED  | 


With  this  required  command  the  user  controls  the  reading  of  values  of  the  indicated  variables  from 
file.  Command  READINP  must  follow  command  INPGRID. 

If  the  variables  are  in  one  file,  then  the  READINP  commands  should  be  given  in  the  same  sequence 
in  which  the  variables  appear  in  the  file. 

BOTTOM  With  this  option,  the  user  indicates  that  bottom  levels  (m)  are  to  be 

read  from  file  (bottom  level  positive  downward  relative  to  an  arbitrary 
horizontal  datum  level).  The  sign  of  the  input  can  be  changed  with 
option  [fac]  =  -1.  (See  below). 

WLEV  With  this  option,  the  user  indicates  that  water  levels  (m)  are  to  be  read 

from  file  (water  level  positive  upward  relative  to  the  same  datum  level 
as  used  in  option  BOTTOM).  Sign  of  input  can  be  changed  with 
option  [fac]  =  -1.  If  the  water  level  is  constant  in  space  and  time,  use 
the  command  SET  to  add  this  water  level  to  the  water  depth. 

CURRENT  Rectilinear  (curvilinear)  input  grid.  With  this  option,  the  user 

indicates  that  the  x-  and  y-components  are  to  be  read  from  one  and  the 
same  READINP  command.  Under  this  option  SWAN  reads  the  x- 
components  (x*-components)  first,  and  then  the  y-components  (y  - 
components),  (see  below),  x  -  and  y  -components  are  taken  along  the 
directions  of  the  grid  lines  of  the  curvilinear  grid!  If  the  current 
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velocity  is  relatively  large,  e.g.,  the  Froude  number  U  /  Jgd  is  larger 

than  0.8,  it  will  be  reduced  such  that  the  Froude  number  becomes 
equal  to  0.8. 


FRICTION 


WIND 


[fac] 


'fname  1  ’ 
SERIES 


'fname2' 


[idla] 


With  this  option  the  user  indicates  that  friction  coefficient  is  to  be  read 
from  file  for  Collins:  cfw  and  for  Madsen:  Kn,  no  space-  or  time- 
variable  coefficient  for  the  JONSWAP  expression  (see  command 
FRICTION,  Section  4.12.9.5).  If  the  coefficients  are  constant  in  space 
and  time,  see  command  FRICTION. 

Rectilinear  (curvilinear)  input  grid:  with  this  option  the  user  indicates 
that  the  x-  and  y-component  (x‘-  and  y*-component)  are  to  be  read 
from  one  and  the  same  file  (with  one  READINP  command).  Under 
this  option  SWAN  reads  first  all  x-components  (x’-components),  and 
then  all  y-components  (y*-components),  (see  below),  x*-  and  y*- 
components  are  taken  along  the  directions  of  the  grid  lines  of  the 
curvilinear  grid.  If  the  wind  is  constant  (see  command  WIND, 

Section  4.12.7.3), 

SWAN  multiplies  all  values  that  are  read  from  file  with  FAC.  For 
instance,  if  the  bottom  levels  are  given  in  unit  decimeter,  one  should 
make  [fac]  =  0.1  to  obtain  levels  in  m.  To  change  sign  of  bottom  level 
use  a  negative  value  of  [fac].  Default:  [fac]  =  1. 

Name  of  the  file  with  the  values  of  the  variable. 

With  this  option  (only  for  mode  NONSTATIONARY)  the  user 
indicates  that  the  names  of  the  files  containing  the  nonstationary 
variable(s)  are  located  in  a  separate  file  with  name  ’fname2’. 

Contains  the  names  of  the  files  where  the  variables  are  given.  These 
names  are  to  be  given  in  proper  time  sequence.  SWAN  reads  the  next 
file  when  the  previous  file  end  has  been  encountered.  In  these  files  the 
input  should  be  given  in  the  same  format  as  in  the  above  file  ’fnarnel’ 
(that  implies  that  a  file  should  start  with  the  start  of  an  input  time 
step). 

Prescribes  the  order  in  which  the  values  of  bottom  levels  and  currents 
should  be  given  in  the  file. 

=  1  SWAN  reads  the  map  from  left  to  right  starting  in  the  upper- 
left-hand  corner  of  the  map  (it  is  assumed  that  the  x-axis  of  the 
grid  is  pointing  to  the  right  and  the  y-axis  upwards).  A  new 
line  in  the  map  should  start  on  a  new  line  in  the  file. 

=  2  As  [idla]  =  1  but  a  new  line  in  the  map  need  not  start  on  a  new 
line  in  the  file. 
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[nhedf] 


[nhedt] 


[nhedvec] 


FREE 


FORMAT 


=  3  SWAN  reads  the  map  from  left  to  right  starting  in  the  lower- 

left-hand  comer  of  the  map.  A  new  line  in  the  map  should  start 
on  a  new  line  in  the  file. 

=  4  As  [idla]  =  3  but  a  new  line  in  the  map  need  not  start  on  a  new 
line  in  the  file. 

=  5  SWAN  reads  the  map  from  top  to  bottom  starting  in  the  lower- 
left-hand  comer  of  the  map.  A  new  column  in  the  map  should 
start  on  a  new  line  in  the  file. 

=  6  As  [idla]  =  5  but  a  new  column  in  the  map  need  not  start  on  a 
new  line  in  the  file.  (Default:  [idla]  =  1). 

The  number  of  header  lines  at  the  start  of  the  file.  The  text  in  the 
header  lines  is  reproduced  in  the  print  file  created  by  SWAN  (see 
Section  4.11.2.1).  The  file  may  begin  with  more  header  lines  than 
[nhedf]  because  the  start  of  the  fde  is  often  also  the  start  of  a  time  step 
and  possibly  also  of  a  vector  variable  (each  having  header  lines,  see 
below,  [nhedt]  and  [nhedvec]).  Default:  [nhedf]  =  0. 

Number  of  header  lines  in  the  file  at  the  start  of  each  time  level. 

Note:  Used  only  if  variable  is  time-dependent.  A  time  step  may  start 
with  more  header  lines  than  [nhedt]  because  the  variable  may  be  a 
vector  variable  that  has  its  own  header  lines  (see  below  [nhedvec]). 
Default:  [nhedt]  =  0. 

For  each  vector  variable:  number  of  header  lines  in  the  file  at  the  start 
of  each  component  (e.g.,  x-  or  y-component).  Default:  [nhedvec]  =  0. 

With  this  option  the  user  indicates  that  the  values  are  to  be  read  with 
free  format.  Free  format  is  a  standard  of  FORTRAN.  The  free  format 
conventions  in  reading  from  a  file  are  almost  the  same  as  the 
conventions  for  the  command  syntax  given  in  Appendix  A.  The  most 
important  differences  are: 

1.  There  are  no  continuation  marks.  Reading  continues  until  the 
required  number  of  data  has  been  read  or  until  a  slash  (/)  is 
encountered. 

2.  Input  lines  can  be  longer  than  eighty  characters  (depending  on  the 
operating  system  of  the  computer). 

3.  Comments  are  not  allowed. 

With  free  format  empty  fields,  repetition  factors,  and  closure  of  a  line 
by  a  slash,  may  be  used. 

Indicates  that  fixed  format  (FORTRAN  convention)  is  to  be  used 
when  reading  the  values  from  file.  The  format  can  be  defined  either 
by  giving  the  format  number  [IDFM]  or  the  format  string  ’FORM'. 
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A  user-specified  format  string  according  to  FORTRAN  convention 
e.g.  '((10X,  12F5.0))'. 

This  format  number  is  interpreted  as  follows: 

=  1  Format  according  to  BODKAR  convention  (a  standard  of  the 
Ministry  of  Transport  and  Public  Works  in  the  Netherlands); 

Format  string:  (10X,  12F5.0). 

=  5  Format  (16F5.0),  i.e.  an  input  line  consists  of  16  fields  of  five 
places  each. 

=  6  Format  (12F6.0),  i.e.  an  input  line  consists  of  12  fields  of  six 
places  each. 

=  8  Format  (10F8.0),  i.e.  an  input  line  consists  of  10  fields  of  eight 
places  each. 

UNFORMATTED  A  form  of  reading  without  conversion  (binary  files).  Not 
recommended  for  ordinary  use. 

If  the  file  does  not  contain  a  sufficient  number  of  data  (i.e.  less  than  the  number  of  grid  points  of  the 
input  grid),  SWAN  will  write  an  error  message  to  the  print  file.  If  [itest]  >  0  (see  command  TEST, 
Section  4.12.5,1),  SWAN  will  reproduce  the  data  in  the  print  file  using  the  layout  according  to 
[ldla]  =  1.  The  echo  of  the  data  to  print  file  is  also  made  if  the  READINP  command  is  embedded 
between  two  TEST  commands  in  the  command  file  as  follows: 

TEST  120 
READINP .... 

TESTO 

To  obtain  only  contour  line  plots  or  vector  plots  of  input  quantities  (see  command  PLOTGEOGR, 
Section  4.13.2.6)  without  computations,  e.g.  to  verify  input,  one  should  run  SWAN  with  [itermx]'= 
0  (with  command  NUMERIC). 


4.12.7.3  WIND 
WIND  [vel]  [dir] 


'form' 

[idfm] 


With  this  optional  command  the  user  indicates  that  the  wind  is  constant. 

[vel]  Wind  velocity  at  10-m  elevation  (m/s). 

tdir]  Wind  direction  at  10-m  elevation  (in  degrees,  Cartesian  or  Nautical 

convention.  See  command  SET,  Section  4.12.4.2) 

Both  quantities  are  required  if  this  command  is  used.  Note  that  SWAN  converts  Ul0  to  U .  (see 

Section  5.1.4). 
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4.12.8  Boundary  and  Initial  Conditions  Commands 
4.12.8.1  B0UNDPAR1 


|  ->  JONSWAP  [gamma]  | 

j  I  I  ->  PEAK  | 

BOUNDPAR1  SHAPESPEC  <  PM  >  <  >  & 

|  |  |  MEAN  I 

j  GAUSS  [sigfr]  j 

I  I 

I  BIN  | 

1  ->  POWER  | 

DSPR  <  > 

|  DEGREES  | 


This  command  BOUNDPAR1  SHAPESPEC  defines  the  shape  of  the  spectra  (both  in  frequency 
and  direction)  at  the  boundary  of  the  computational  grid  in  case  of  parametric  spectral  input  (see 
command  BOUNDPAR2,  Section  4.12.8.2). 


JONSWAP 

JONSWAP  spectrum  will  be  used. 

[gamma] 

Peak  enhancement  parameter  of  the  JONSWAP  spectrum.  Default: 

[gamma]  =  3.3. 

PM 

Pierson-Moskowitz  spectrum  will  be  used. 

GAUSS 

A  Gaussian-shaped  frequency  spectrum  will  be  used. 

BIN 

Energy  is  located  in  one  frequency  bin  (the  frequency  bin  closest  to  the  PER 
value  of  command  BOUNDPAR2). 

[sigfr] 

Width  of  the  Gaussian  frequency  spectrum  expressed  as  a  standard 
deviation  in  Hz. 

PEAK 

Default:  the  peak  period  (for  definition  see  Section  4.14)  is  used  as 
characteristic  wave  period. 

MEAN 

TmOl  (for  definition  see  Section  4.14)  is  used  as  the  characteristic  wave 
period. 

DSPR 

Option  for  expressing  the  width  of  the  directional  distribution  (the 
distribution  function  itself  is  cosm  (0-0peak)- 
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POWER 


DEGREES 


Default:  The  directional  width  is  expressed  with  the  power  m  itself.  Note: 
The  directional  resolution  should  accommodate  the  directional  width;  see 
command  CGRID,  Section  4.12.6.1), 

The  directional  width  is  expressed  in  terms  of  the  directional  standard 
deviation  of  the  cosm  (0-0pcak)  distribution  (for  definition  see  Section  4.14). 
Note:  The  directional  resolution  should  accommodate  the  directional  width; 
see  command  CGRID,  Section  4.12.6.1. 


If  this  command  is  not  used,  the  JONSWAP  option  will  be  used  by  SWAN  with  [gamma]  =  3.3  and 
POWER  for  the  directional  width. 

4.12.8.2  BOUNDPAR2 


1  NORTH 

1 

j  NW 

1 

|  WEST 

1 

|SW 

|  1  ->  CCW  I 

|  ->  SIDE 

<  SOUTH 

>  <  > 

| 

1 

|  SE 

1  1  CLOCKWISE  I 

1 

1 

1 

(EAST 

| 

1 

j  NE 

1 

I 

> 

BOUNDPAR2  < 

[->  XY 

<  M  [y]  >  | 

I 

1  SEGMENT 

< 

> 

| 

1  M 

<  fi]  U]  >  1 

I  CONSTANT  PAR  [hs]  [per]  [dir]  [dd] 


|  VARIABLE  PAR  <  [len]  [hs]  [per]  [dir]  [dd]  > 


Command  BOUNDPAR2,  consisting  of  two  parts,  defines  parametric  spectra  at  the  boundary.  The 
first  part  defines  the  boundary  side  or  segment  where  the  spectra  will  be  given.  The  second  defines 
the  spectra]  parameters  of  these  spectra.  Only  the  incoming  wave  components  of  these  spectra  are 
used  by  SWAN.  The  fact  that  complete  spectra  are  calculated  at  the  model  boundaries  from  the 
spectral  parameters  should  not  be  misinterpreted.  Only  the  incoming  components  are  effective  in 
the  computation. 

There  are  two  ways  to  define  the  part  of  the  boundary  at  which  the  spectra  are  imposed.  The  first 
way  (SIDE)  is  easiest  if  the  boundary  is  one  full  side  of  the  computational  grid.  The  second 
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(SEGMENT)  can  be  used  if  the  boundary  segment  goes  around  the  corner  of  the  grid,  or  if  the 
segment  is  only  part  of  one  side  of  the  grid. 

Command  BOUNDPAR2  can  be  given  a  number  of  times,  such  as  to  define  incident  wave  fields  on 
various  sides  or  segments  of  the  boundary.  One  BOUNDPAR2  command  can  be  used  for  only  one 
side  or  one  contiguous  segment. 


SIDE  The  boundary  is  one  full  side  of  the  computational  grid  (in  1-D  cases 

either  of  the  two  ends  of  the  1  -D  grid). 

NORTH, ...  Indicates  on  which  side  the  boundary  condition  is  applied;  N  means  the 

boundary  is  the  north  edge  (if  present)  of  the  computational  area, 
likewise  for  W  (west),  S  (south),  E  (east),  NW  (northwest),  NE 
(northeast),  SW  (southwest)  and  SE  (southeast).  The  side  does  not  have 
to  face  exactly  the  given  direction  because  the  nearest  direction  of  the 
normal  to  the  side  is  taken.  For  curvilinear  grids  the  direction  is 
determined  as  the  normal  to  the  sum  of  the  vectors  joining  the  grid 
points  on  the  boundary.  If  there  is  an  interruption  in  the  boundary  due  to 
the  occurrence  of  exception  values  then  the  interruption  is  ignored  in  the 
summation.  Note:  For  Cartesian  coordinates  the  direction  of  the 
problem  coordinate  system  must  be  defined  by  the  user  (see  command 
SET.. [north],  Section  4.12.4.2).  Default:  the  positive  x-axis  points  east. 

CCW,  CLOCKWISE  See  description  of  [len]  below;  these  options  are  only  effective  if  the 

option  VARIABLE  is  used. 

SEGMENT  SEGMENT  is  used  if  SIDE  is  not,  i.e.  either  the  boundary  segment  goes 

around  a  comer  of  the  grid,  or  the  segment  is  only  part  of  one  side  of  the 
grid.  The  distance  along  the  segment  (see  [len]  below)  is  measured 
from  the  first  point  of  the  segment  (see  XY  or  U). 

XY  The  segment  is  defined  by  a  series  of  points  of  problem  coordinates; 

these  points  do  not  have  to  coincide  with  grid  points.  The  (straight)  line 
connecting  two  points  must  be  close  to  grid  lines  of  the  computational 
grid  (the  maximum  distance  is  one  tenth  of  the  length  of  the  straight 
line).  This  option  is  default. 

[x],  [y]  Problem  coordinates  of  a  point  of  the  boundary  segment  (see  command 

COORD,  Section  4.12.4.4). 

IJ  The  segment  is  defined  by  means  of  a  series  of  computational  grid 

points  given  in  terms  of  grid  indices  (origin  at  0,0);  not  all  grid  points  on 
the  segment  have  to  be  mentioned.  If  two  points  are  on  the  same  grid 
line,  intermediate  points  are  assumed  to  be  on  the  segment  as  well. 
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ffl,  01 

CONSTANT 

VARIABLE 


PAR 

[hs] 

[per] 


[dir] 


[dd] 


[len] 


Grid  indices  of  a  point  of  the  segment.  Values  of  [i]  range  between  0 
and  [mxc]  (see  command  CGRED,  Section  4.12.6.1),  values  of  [j] 
between  0  and  [myc]  (inclusive). 

With  this  option  the  wave  spectra  are  constant  along  the  side  or 
segment. 

With  this  option  the  wave  spectra  can  vary  along  the  side  or  segment. 
The  incident  wave  field  is  prescribed  at  a  number  of  points  of  the  side  or 
segment.  Their  distance  from  the  starting  point  of  the  side  or  segment 
characterizes  the  points.  SWAN  calculates  the  wave  spectra  for  grid 
points  on  the  boundary  of  the  computational  grid  by  the  spectral 
interpolation  technique  described  in  Section  4.7.2. 

The  wave  spectra  are  defined  by  means  of  the  following  spectral 
parameters  (see  command  BOUNDPAR1,  Section  4.12.8.1  for  spectral 
shape). 

The  significant  wave  height  (in  m). 

The  characteristic  period  of  the  energy  spectrum  (relative  frequency; 
which  is  equal  to  absolute  peak  frequency  in  the  absence  of  currents), 
[per]  is  the  value  of  the  peak  period  (in  s)  if  option  PEAK  is  chosen  in 
command  BOUNDPAR1.  [per]  is  the  value  of  the  mean  period  if  option 
MEAN  is  chosen  in  command  BOUNDPAR1. 

The  peak  wave  direction  (0peak>  direction  in  degrees;  constant  over 
frequencies). 

Coefficient  of  directional  spreading;  a  cosm(0)  distribution  is  assumed, 
[dd]  is  interpreted  as  the  directional  standard  deviation  in  degrees  if  the 
option  DEGREES  is  chosen  in  the  command  BOUNDPAR1. 

[dd]  is  interpreted  as  the  power  m  if  the  option  POWER  is  chosen  in  the 
command  BOUNDPAR1. 

The  distance  from  the  first  point  of  the  side  or  segment  to  the  point 
along  the  side  or  segment  for  which  the  incident  wave  spectrum  is 
prescribed.  Note:  The  points  do  not  have  to  coincide  with  grid  points  of 
the  computational  grid,  [len]  is  the  distance  in  m,  not  in  grid  steps.  The 
values  of  [len]  should  be  given  in  ascending  order.  The  length  along  a 
SIDE  is  measured  in  clockwise  or  counterclockwise  direction, 
depending  on  the  options  CCW  or  CLOCKW.  The  option  CCW  is 
default.  For  a  SEGMENT  the  length  is  measured  from  the  indicated 
begin  point  of  the  segment. 
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4.12.8.3  BOUNDSPEC 


|  NORTH  j 

j  NW  j 

j  WEST  j 

ISW  |  I  ->  CCW 


1  ->  SIDE 

<  SOUTH  > 

<  > 

i 

1 

|SE  | 

1  CLOCKWISE  1 

l 

1 

| EAST  | 

I 

1 

|NE  | 

I 

BOUNDSPEC  < 

1 

|->XY  < 

[x]  [y]  >  | 

> 

I 

& 

|  SEGMENT 

< 

> 

I 

1  H  < 

[i]  [j]  >  1 

1  CONSTANT  FILE  ‘fname’  Tseal 

1 

1 

| 

1 

< 

1 

> 

1 

l 

|  VARIABLE  FILE  <  flenl  ‘fname’ 

1 

[seq]  >  | 

Command  BOUNDSPEC,  which  consists  of  two  parts,  defines  spectra  at  the  boundary.  The  first 
part  defines  the  boundary  side  or  segment  where  the  spectra  will  be  given.  The  second  defines  the 
source  of  these  spectra  (files).  Note  that  only  the  incoming  wave  components  of  these  spectra  are 
used  by  SWAN.  The  fact  that  complete  spectra  are  calculated  from  the  spectral  parameters  should 
not  be  misinterpreted.  Only  the  incoming  components  are  effective  in  the  computation. 

This  BOUNDSPEC  command  can  be  given  a  number  of  times;  i.e.  to  define  incident  wave  fields  on 
various  segments  of  the  boundary.  One  BOUNDSPEC  command  can  be  used  for  only  one 
contiguous  segment. 


SIDE 

NORTH, ... 

CCW,  CLOCKWISE 

SEGMENT 

XY 

[x],  [y] 

IJ 


See  command  BOUNDPAR2,  Section  4.12.8.2, 
See  command  BOUNDPAR2,  Section  4.12.8.2. 
See  command  BOUNDPAR2,  Section  4.12.8.2. 
See  command  BOUNDPAR2,  Section  4.12.8.2, 
See  command  BOUNDPAR2,  Section  4.12.8.2, 
See  command  BOUNDPAR2,  Section  4.12.8.2, 
See  command  BOUNDPAR2,  Section  4.12.8.2. 
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[i],Ul 

CONSTANT 

VARIABLE 

FILE 


'fname' 

[seq] 


See  command  BOUNDPAR2,  Section  4.12.8.2, 

See  command  BOUNDPAR2,  Section  4.12.8.2. 

See  command  BOUNDPAR2,  Section  4.12.8.2, 

The  incoming  wave  data  are  read  from  a  file.  There  are  three  types  of 
files: 

1 .  TPAR  files  containing  nonstationary  wave  parameters, 

2.  Files  containing  stationary  or  nonstationary  1-D  spectra  (usually  from 
measurements), 

3.  Files  containing  stationary  or  nonstationary  2-D  spectra  (from  other 
computer  programs  or  other  SWAN  runs). 

A  TPAR  file  is  used  for  only  one  location.  The  string  TPAR  is  on  the  first 
line  of  the  file  and  subsequent  lines  each  contain  five  numbers  including 
Time  (ISO  notation),  Hs,  Period  (average  or  peak  period  depending  on  the 
choice  given  in  command  BOUND  SHAPE),  Peak  Direction  (Nautical  or 
Cartesian,  depending  on  command  SET),  Directional  spread  (in  degrees  or 
as  power  of  Cos  depending  on  the  choice  given  in  command  BOUND 
SHAPE). 


Example  of  a  TPAR  file: 
TPAR 


19920516 . 1300 

4.2 

12  . 

-110  . 

22  . 

19920516 . 1800 

4.2 

12  . 

-110  . 

22  . 

19920517 .0000 

1.2 

8  . 

-110. 

22  . 

19920517.1200 

1 . 4 

8.5 

I 

CD 

O 

26 

19920517.2000 

0.9 

6.5 

-95. 

28 

The  structure  of  the  files  containing  1-D  or  2-D  spectra  is  described  in 
Appendix  D  (there  is  no  relation  to  the  definition  of  the  boundary  file 
generated  by  WAM  or  WAVEWATCH  HI).  1-D  and  2-D  files  can  be 
used  for  stationary  and  nonstationary  boundary  conditions  and  for  one  or 
more  locations.  The  spectral  frequencies  (and  directions  in  the  case  of  a 
2-D  spectrum)  do  not  have  to  coincide  with  the  frequencies  and  directions 
used  in  the  present  SWAN  run.  In  a  nested  run,  however,  SWAN  will 
interpolate  to  these  frequencies  and  directions.  The  coordinates  of 
locations  in  the  1-D  and  2-D  files  are  ignored  when  SWAN  reads  this  file 
(SWAN  uses  the  geographical  information  in  the  BOUNBSPEC 
command  instead). 

Name  of  the  file  containing  the  boundary  condition. 

Identification  number  of  geographic  location  in  the  file  (see  Appendix  D). 
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It  is  useful  for  files  that  contain  spectra  for  more  than  one  location. 
Default:  [seq]  =  1 . 

Note:  A  TPAR  file  always  contains  only  one  location,  therefore,  [seq] 
must  always  be  one. 

[len]  See  command  BOUNDPAR2,  Section  4.12.8.2, 


4.12.8.4  BOUNDNEST1 


I  ->  CLOSED  | 

BOUNDNEST1  NEST  'fname'  <  > 

|  OPEN  | 


With  this  optional  command  a  nested  SWAN  run  can  be  completed  with  the  boundary  conditions 
obtained  from  a  coarse  grid  SWAN  run,  generated  in  a  previous  SWAN  run  with  command 
NESTOUT.  This  should  not  to  be  confused  with  the  BOUNDNEST1  option  NEST.  For  a  nested 
SWAN  run  the  CGRID  command  is  given  to  define  the  computational  grid  prior  to  giving  the 
BOUNDNEST1  command.  The  computational  grid  for  SWAN  in  geographic  space  is  the  area 
bounded  by  the  SWAN  coarse  run  nest  (SWAN  boundary  points  of  the  nest).  This  implies  that  the 
boundaries  of  the  SWAN  coarse  run  nest  and  the  boundaries  of  the  SWAN  nested  computational 
area  should  be  almost  identical  (see  below).  The  spectral  frequencies  and  directions  of  the  coarse 
grid  run  do  not  have  to  coincide  with  the  frequencies  and  directions  used  in  the  nested  SWAN  run 
(for  definition  see  command  CGRID,  Section  4.12.6.1).  SWAN  will  interpolate  to  these 
frequencies  and  directions  in  the  nested  run  (see  Section  4.7.2). 

Use  command  NGRID  to  generate  the  nest  boundary  in  the  coarse  grid  run.  For  the  nested  run,  use 
the  command  CGRID  with  identical  geographical  information  except  the  number  of  meshes,  which 
will  be  much  higher  for  the  nested  run. 

A  nested  SWAN  run  must  use  the  same  coordinate  system  as  the  coarse  grid  SWAN  run.  A 
curvilinear  grid  may  be  used  in  the  nested  grid  but  the  boundaries  of  this  nest  should  conform  to  the 
rectangular  course  grid  nest  boundaries. 

NEST  Indicates  that  the  boundary  conditions  are  to  be  retrieved  from  a  file  created  by 

a  previous  SWAN  run  (the  present  SWAN  run  is  a  nested  run).  The  spectral 
frequencies  (and  directions,  for  a  2-D  spectrum)  of  the  previous  run  do  not 
have  to  coincide  with  the  frequencies  and  directions  used  in  the  present  SWAN 
run  (see  command  CGRID,  Section  4.12.6.1).  SWAN  will  interpolate  the 
energy  densities  to  these  frequencies  and  directions  (see  Section  4.7.2). 

’fname1  Name  of  the  file  containing  the  boundary  conditions  for  the  present  run,  created 

by  the  previous  SWAN  coarse  grid  run.  This  file  is  structured  according  to  the 
rules  given  in  Appendix  D  for  2-D  spectra. 
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CLOSED  The  boundary  represented  in  the  file  is  a  closed  rectangle.  This  is  always  the 

case  if  the  NESTOUT  command  was  used  to  generate  the  boundary  condition 
file. 

OPEN  The  boundary  represented  in  the  file  is  not  a  closed  rectangle.  This  is  always 

the  case  if  the  NESTOUT  command  was  used  to  generate  the  boundary 
condition  file. 

If  the  user  wishes  to  view  the  location  of  the  nested  grid,  e.g.  in  relation  to  the  bathymetry  (defined 
by  sname  =  BOTTGRID ),  the  command  PLOTGEOGR  should  be  used.  If  the  name  of  the  nested 
grid  is  'sname'  =  'NG',  the  command  should  be: 

PLOTGEOGR  'BOTTGRID'  ISO  BOTTOM  LOCATION  'NG'  (see  command  PLOTGEOGR, 
Section  4.13.2.7), 

The  BOUNDNEST  command  is  not  available  for  1-D  computations.  In  such  cases,  the  commands 
SPECOUT  and  BOUNDSPEC  may  be  used  for  the  same  purpose.  Use  command  CGRID  to  define 
the  computational  grid. 


4.12.8.5  BOUNDNEST2  WAMNEST 


l->  CRAY  | 

|  UNFORMATTED  <  - 

I  |  WKSTAT  | 

BOUNDNEST2  WAMNEST  'fname'  < 


I 

I 

> [xgc]  [ygc] 


FREE 


BOUNDNEST2  WAMNEST  is  an  optional  command  (not  fully  tested)  in  which  a  nested  SWAN 
run  can  be  carried  out  with  the  boundary  conditions  obtained  from  a  coarse  grid  WAM  Cycle  3  and 
4  run.  For  a  nested  SWAN  run  the  user  must  give  the  CGRID  command  to  define  the 
computational  grid  before  using  BOUNDNEST2.  The  computational  grid  for  SWAN  in  geographic 
space  is  the  area  bounded  by  the  WAM  coarse  run  nest  (WAM  boundary  points  of  the  nest).  This 
implies  that  the  boundaries  of  the  WAM  nest  and  the  boundaries  of  the  SWAN  computational  area 
should  be  (nearly)  identical  (see  below).  The  spectral  frequencies  and  directions  of  the  coarse  grid 
run  do  not  have  to  coincide  with  the  frequencies  and  directions  used  in  the  nested  SWAN  run 

(CGRID).  SWAN  will  interpolate  to  these  frequencies  and  directions  in  the  nested  run  (see  Section 
4.7.3), 

Note:  SWAN  will  accept  a  WAM  output  location  only  if  the  SWAN  grid  point  on  the  nest 
boundary  lies  within  a  rectangle  between  two  consecutive  WAM  output  locations.  The  width 
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between  the  output  locations  must  be  equal  to  0.1  times  the  distance  on  either  side  of  the  line 
between  the  WAM  output  locations. 

Option  BOUNDNEST  is  not  available  for  1-D  computations. 

A  nested  SWAN  run  may  use  either  Cartesian  or  spherical  coordinates.  A  curvilinear  grid  may  be 
used  in  the  nested  grid  but  the  boundaries  of  this  nest  should  conform  to  the  rectangular  course  grid 
nest  boundaries. 

WAM  output  files  are  unformatted  (binary).  This  implies  that  WAM  and  SWAN  must  run  on  the 
same  computer.  The  option  FREE  is  available  in  command  BOUNDNEST  when  WAM  and 
SWAN  run  on  different  types  of  machines  because  binary  files  do  not  transfer  properly.  The 
distributed  version  of  WAM  does  not  support  the  required  free  format  nesting  output.  WAM  users 
must  modify  WAM  so  that  WAM  output  files  can  be  read  in  free  format,  i.e.  with  at  least  a  blank  or 
comma  between  numbers. 

'fname'  A  file  name  that  contains  all  WAM  filenames  containing  the  nested 

boundary  conditions  in  time-sequence  (usually  one  file  per  day).  For 
example,  the  contents  of  'fname'  may  appear  as: 

CB09212010000 
CB09  212020000 
CB09212030000 

etc . 

SWAN  will  read  the  boundary  data  from  these  WAM  files  one  after  the 
other. 

Indicates  that  the  WAM  files  are  binary. 

Input  will  be  read  from  file  created  by  the  CRAY  version  of  WAM. 

Input  will  be  read  from  file  created  by  the  WORKSTATION  version  of 
WAM. 

The  user  indicates  that  the  WAM  files  may  be  read  with  free  format.  These 
files  are  not  generated  standard  by  WAM. 

If  SWAN  is  used  with  Cartesian  coordinates  [xgc]  is  the  longitude  of  the 
southwest  comer  of  the  SWAN  computational  grid  (in  degrees).  If  the 
southwest  comer  of  the  nest  in  the  WAM  computation  is  on  land  this  value 
is  required.  SWAN  ignores  [xgc]  if  it  is  used  with  spherical  coordinates. 
Default:  The  location  of  the  first  spectrum  encountered  in  the  nest  file. 

If  SWAN  is  used  with  Cartesian  coordinates  [ygc]  is  the  latitude  of  the 
southwest  comer  of  SWAN  computational  grid  (in  degrees).  If  the 


UNFORMATTED 

CRAY 

WKSTAT 

FREE 

[xgc] 

[ygc] 
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southwest  corner  of  the  nest  in  the  WAM  computation  is  on  land  this  value 
is  required.  SWAN  ignores  [ygc]  if  it  is  used  with  spherical  coordinates. 
Default:  The  location  of  the  first  spectrum  encountered  in  the  nest  file. 


4.12.8.6  BOUNDNEST3  WWII1 


I  ->  CLOSED 

BOUNDNEST3  WWffl  'fname'  < 

I  OPEN 


>  [xgc] [ygc] 


With  this  optional  command  (not  fully  tested)  a  nested  SWAN  run  can  be  carried  out  with  the 
boundary  conditions  obtained  from  a  coarse  grid  WAVEWATCH  in  run.  For  this  nested  SWAN 
run  the  user  must  give  the  CGRID  command  before  the  BOUNDNEST3  command.  The 
computational  grid  for  SWAN  in  geographic  space  is  the  area  bounded  by  the  WAVEWATCH  in 
nest  (WAVEWATCH  m  boundary  points  of  the  nest).  Therefore  the  boundaries  of  the 
WAVEWATCH  m  nest  and  the  SWAN  computational  area  should  be  (nearly)  identical  (see 
below).  The  spectral  frequencies  and  directions  of  the  coarse  grid  run  do  not  have  to  coincide  with 
the  frequencies  and  directions  used  in  the  nested  SWAN  run  (CGRID  command);  SWAN  will 
interpolate  to  these  frequencies  and  directions  in  the  nested  run  (see  Section  4.7.2). 

The  output  files  of  WAVEWATCH  HI  (Version  1 . 1 8,  as  distributed  by  NOAA)  must  be  created 
with  the  WAVEWATCH  HI  post-processor  as  output  transfer  files  with 

WW_3  OUTP  (output  type  1  sub  type  3) 

at  the  locations  along  the  nest  boundary  (i.e.  computational  grid  points  in  WAVEWATCH  III). 
These  locations  are  equal  to  the  comer  points  of  the  SWAN  nested  grid  and  are  optionally 
distributed  between  the  nested  SWAN  comer  points.  The  boundary  of  the  WAVEWATCH  IH 
nested  grid  need  not  be  closed  and  may  cover  land.  WAVEWATCH  III  will  output  the  locations  in 
sequence,  moving  along  the  nest  boundary  either  clockwise  or  counter-clockwise).  SWAN  will 
accept  WAVEWATCH  HI  output  locations  only  if  the  SWAN  nested  boundary  grid  lies  within  a 
rectangle  between  two  consecutive  WAVEWATCH  III  output  locations  with  a  width  equal  to  0.1 
times  the  distance  between  these  output  locations  on  either  side  of  the  line  between  these 
WAVEWATCH  III  output  locations. 

A  nested  SWAN  run  may  use  either  Cartesian  or  spherical  coordinates.  A  curvilinear  grid  may  be 
used  in  the  nested  grid  but  the  boundaries  of  this  nest  should  conform  to  the  rectangular  course  grid 
nest  boundaries.  ’  e 


’fname’ 


Name  of  the  file  that  contains  the  spectra  computed  by  WAVEWATCH  III. 


CLOSED 


The  boundary  condition  represented  in  the  file  is  defined  on  a  closed 
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rectangle. 

OPEN  The  curve  on  which  the  boundary  condition  is  given,  is  not  closed. 

[xgc]  If  SWAN  is  used  with  Cartesian  coordinates,  [xgc]  is  the  longitude  of  the 

southwest  comer  of  SWAN  computational  grid  (in  degrees).  This  value  is 
required. 

If  SWAN  is  used  with  spherical  coordinates,  SWAN  ignores  [xgc]. 
Default:  The  location  of  the  first  spectrum  encountered  in  the  nest  file. 

[ygc]  If  SWAN  is  used  with  Cartesian  coordinates,  [ygc]  is  the  latitude  of  the 

southwest  comer  of  SWAN  computational  grid  (in  degrees).  This  value  is 
required. 

If  SWAN  is  used  with  spherical  coordinates;  SWAN  ignores  [ygc]. 
Default:  The  location  of  the  first  spectrum  encountered  in  the  nest  file. 

4.12.8.7  INITIAL 


|  ->  DEFAULT  | 

I  I 

|  ZERO  | 

INITIAL  <  > 

|  PAS  [hs]  [per]  [dir]  [dd]  | 

I  I 

|  HOTSTART  'fname'  | 


This  command  can  be  used  to  specify  the  initial  values  for  a  stationary  (INITIAL  HOTSTART 
only)  or  nonstationary  computation.  The  initial  values  thus  specified  override  the  default 
initialization  (see  Section  4.7.2),  It  is  possible  to  obtain  an  initial  state  by  carrying  out  a  previous 
stationary  or  nonstationary  computation. 

DEFAULT  The  initial  spectra  are  computed  from  the  local  wind  velocities  using  the  deep¬ 
water  growth  curve  of  Kahma  and  Calkoen  (1992)  cut  off  at  values  of 
significant  wave  height  and  peak  frequency  from  Pierson  and  Moskowitz 
(1964).  The  average  spatial  step  size  over  the  model  area  is  used  as  fetch  with 
local  wind.  The  shape  of  the  spectrum  is  default  JONSWAP  with  a  cos2 
directional  distribution  (options  are  available:  see  command  BOUNDPAR1 
SHAPE,  Section  4.12.8.1). 

ZERO  The  initial  spectral  densities  are  all  0;  note  that  if  waves  are  generated  in  the 

model  only  by  wind,  waves  can  become  non-zero  only  by  the  presence  of  the 
"A"  term  in  the  growth  model  (see  the  keyword  AGROW  in  command  GEN3 

Section  4.12.9.3). 
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The  spectra  in  the  entire  computational  area  are  generated  from  integral 
parameters  [hs],  etc.,  in  the  same  way  as  done  for  the  boundary  using  the 
command  BOUNDPAR2. 

The  significant  wave  height. 

Characteristic  wave  period  of  the  energy  spectrum  (either  peak  or  mean  period, 
as  determined  by  the  options  PEAK  and  MEAN  in  the  command 
BOUNDSPEC  SHAPE). 

The  peak  wave  direction  (direction  in  degrees.  Nautical  or  Cartesian 
convention,  see  command  SET,  Section  4.12.4.2). 

The  coefficient  of  directional  spreading;  a  cosm  (0)  distribution  is  assumed.  See 
the  options  DEGREES  and  POWER  in  the  command  BOUNDSPEC  SHAPE 
Section  4.12.8.3. 

HOTSTART  Initial  wave  field  is  read  from  file.  This  file  was  generated  in  a  previous 
SWAN  run  by  means  of  the  HOTFILE  command.  If  the  previous  run  was 
nonstationary,  the  time  found  on  the  file  will  be  assumed  to  be  the  initial  run 
time.  The  computational  grid  (both  in  geographical  space  and  in  spectral  space) 
must  be  identical  to  the  one  in  which  the  initial  wave  field  was  computed. 

fname’  Name  of  the  file  containing  the  initial  wave  field. 


4.12.9  Physics  Commands 
4.12.9.1  GEN1 

GEN1  [cflO]  [cf20]  [cf30]  [cf40]  [edmlpm]  [cdrag]  [umin]  [cfpm] 


PAR 

fhs] 

[per] 

[dir] 

[dd] 


With  this  command  the  user  indicates  that  SWAN  should  run  in  first-generation  mode  (see  Section 
5.1). 

[cflO]  Controls  the  linear  wave  growth.  Default:  [cflO]  =  188. 

[cf20]  Controls  the  exponential  wave  growth.  Default  [cf20]  =  0.59. 

[cf30]  Controls  the  exponential  wave  growth.  Default  [cf30]  =  0. 12. 

[cf40]  Controls  the  dissipation  rate,  i.e.,  the  time  decay  scale.  Default  [cf40]  =  250. 
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[edmlpm]  Maximum  non-dimensionless  energy  density  of  the  wind  sea  part  of  the 

spectrum  according  to  Pierson  Moskowitz  (1964).  Default  [edmlpm]  =  0.0036. 

[cdrag]  Drag  coefficient.  Default  [cdrag]  =  0.0012. 

[umin]  Minimum  wind  velocity  (relative  to  current;  all  wind  speeds  are  taken  at  10  m 

above  sea  level).  Default  [umin]  =  1 . 

[cfpm]  Coefficient  that  determines  the  Pierson  Moskowitz  frequency. 

Default  [cfpm]  =  0.13. 


4.12.9.2  GEN2 _ 

GEN2  [cflO]  [cf20]  [cf30]  [cf40]  [cf50]  [cf60]  [edmlpm]  [cdrag]  [umin]  [cfpm] 


GEN2  indicates  that  SWAN  should  run  in  second-generation  mode  (see  Section  5.1).  The 
variables  are  identical  to  those  in  the  GEN  1  command  except  that  [cf50]  and 
[cf60]  are  added. 

[cf50]  Controls  the  spectral  energy  scale  of  the  limit  spectrum. 

Default  [cf50]  =  0.0023. 

[cf60]  Controls  the  spectral  energy  scale  of  the  limit  spectrum. 

Default  [cf60]  = -0.223. 


4.12.9.3  GEN3 


|  JANSSEN  [cdsl]  [delta]  | 

GEN3  <  >  & 

|  KOMEN  [cds2]  [stpm]  | 


(OUADRUPL  [iquad]  [lambda]  [Cnl4]  [Cshl]  [Csh2]  [Csh3]  )  (AGROW  [a]) 


With  this  command  the  user  indicates  that  SWAN  should  run  in  third-generation  mode  for  wind 
input,  quadruplet  interactions  and  whitecapping  (see  Section  5.1).  Triads,  bottom  friction  and 
depth-induced  breaking  are  not  activated  by  GEN3.  The  option  GEN3  KOMEN  is  default.  The 
DIA  of  the  quadruplet  interactions  is  always  active  with  this  command  but  can  be  deactivated  (see 
command  OFF,  Section  4.12.9.9)  and  is  a  poor  approximation  for  long-crested  waves  and 
frequency  resolutions  differing  widely  from  10%  (see  command  CGRID,  Section  4.12.6.1). 


63 


SWAN  User’s  Manual 


JANSSEN 

[cdsl] 

[delta] 

KOMEN 

[cds2] 

[stpm] 

QUADRUPL 

[iquad] 

[lambda] 

[CnI4] 

[Cshl] 

[Csh2] 


Linear  growth:  Cavaleri  and  Malanotte-Rizzoli  (1981),  activated 

only  if  the  keyword  AGROW  is  present  (see  below). 

Exponential  growth:  Janssen  (1989,  1991). 

Coefficient  for  determining  the  rate  of  dissipation  (=Cds/sPM4  in  Eq.  16).  Default 
[cdsl]  =  4.5. 

Coefficient  that  determines  the  dependency  of  the  whitecapping  on  wave 
number  (mix  with  Komen  et  al.  (1984)  formulation).  Default  [delta]  =  0.5  (see 
Section  5.1). 

Linear  growth:  Cavaleri  and  Malanotte-Rizzoli  (1981),  activated  only  if 

the  keyword  AGROW  is  present  (see  below). 

Exponential  growth:  Komen  et  al.  (1984). 

Coefficient  for  determining  the  rate  of  dissipation  (=  Cds  in  Eq.  16).  Default 
[cds2] =  2.36e-5 

Value  of  the  wave  steepness  for  a  Pierson-Moskowitz  spectrum  (=  sPm2  with 
SpM  from  Eq  16).  Default  [stpm]  =  3.02e-3. 

With  this  option  the  user  can  influence  the  computation  of  nonlinear  quadruplet 
wave  interactions.  Default:  the  quadruplets  are  included  in  the  computations. 
Quadruplets  may  be  deactivated  with  command  OFF  QUAD. 

The  quadruplets  can  be  integrated  by  three  different  numerical  procedures: 

=  1  Semi-implicit  computation  of  the  nonlinear  transfer  per  sweep; 

=  2  Fully  explicit  computation  of  the  nonlinear  transfer  per  sweep; 

=  3  Fully  explicit  computation  of  the  nonlinear  transfer  per  iteration. 

Default:  [iquad]  =  2. 

Coefficient  for  quadruplet  configuration  (see  Eq.  27,  Section  5.1.4.5.1). 

Proportionality  coefficient  for  quadruplet  interactions  (see  Eq.  30,  Section 
5.1.4.5.1). 


[Csh3] 


Coefficient  for  shallow  water  scaling  (see  Eq.  32,  Section  5.1.4.5.1), 
Coefficient  for  shallow  water  scaling  (see  Eq.  32,  Section  5.1.4.5.1), 
Coefficient  for  shallow  water  scaling  (see  Eq.  32,  Section  5.1.4.5.1), 
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AGROW  If  this  keyword  is  used,  the  wave  growth  term  of  Cavaleri  and  Malanotte  (1981) 

is  activated.  If  this  keyword  is  NOT  used,  the  wave  growth  term  of  Cavaleri 
and  Malanotte  (1981)  is  NOT  activated.  In  nonstationary  runs  SWAN  will  start 
with  an  initial  state  generated  by  command  INIT  (default  if  not  given  by  the 
user).  In  stationary  runs  SWAN  will  start  with  a  first  guess. 

[a]  If  the  wave  growth  term  of  Cavaleri  and  Malanotte  (1981)  is  activated,  [a]  is  the 

proportionality  coefficient  in  that  term  (see  Section  5.1.4). 

Default  [a]  =  0.0015. 


4.12.9.4  BREAKING  CONSTANT 
BREAKING  CONSTANT  [alpha]  [gamma] 


With  this  command  the  user  can  influence  depth-induced  wave  breaking  in  shallow  water  in  the 
SWAN  model  (see  Section  5.1). 


If  this  command  is  not  used,  SWAN  will  account  for  wave  breaking  anyhow  (with  default  options 
and  values).  If  the  user  wants  to  specifically  ignore  wave  breaking,  he  should  use  the  command 
OFF  BREAKING. 

CONSTANT 

Indicates  that  a  constant  breaker  parameter  is  to  be  used. 

[alpha] 

Proportionality  coefficient  of  the  rate  of  dissipation.  Default  [alpha]  =  1.0. 

[gamma] 

The  ratio  of  maximum  individual  wave  height  over  depth.  Default  [gamma] 

=  0.73. 

4.12.9.5  FRICTION 

|  ->  JONSWAP  [cfjon] 

1 

FRICTION 

1 

<  COLLINS  [cfw] 

1 

|  MADSEN  [knl 

With  this  optional  command  the  user  can  activate  bottom  friction  (see  Section  5.1).  If  this 
command  is  not  used,  SWAN  will  not  account  for  bottom  friction. 

In  SWAN  the  three  different  formulations  available  are  Hasselmann  et  al.  (1973,  JONSWAP), 
Collins  (1972),  and  Madsen  et  al.  (1988).  The  default  option  is  JONSWAP. 

JONSWAP  Indicates  that  the  semi-empirical  expression  derived  from  the  JONSWAP 
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results  for  bottom  friction  dissipation  (Hasselmann  et  al.,  1973,  JONSWAP) 
should  be  activated.  This  option  is  default. 

[cfjon]  Coefficient  of  the  JONSWAP  formulation,  [cfjon]  is  equal  to  0.038  mV3  for 

swell  conditions  and  equal  to  0.067  mV3  for  wind  sea  conditions.  Default: 
[cfjon]  =  0.067  m2s'3 

COLLINS  Indicates  that  the  expression  of  Collins  (1972)  should  be  activated. 

[cfw]  Collins  bottom  friction  coefficient,  (see  Section  5.1).  Default:  [cfw]  =  0.015. 

Note  that  [cfw]  is  allowed  to  vary  over  the  computational  region.  In  that  case, 
use  the  commands  INPGRID  FRICTION  and  READINP  FRICTION  to  define 
and  read  the  friction  data.  The  command  FRICTION  is  still  required  to  define 
the  type  of  friction  expression.  The  value  of  [cfw]  in  this  command  is  then 
not  required  and  will  be  ignored. 

MADSEN  Indicates  that  the  expression  of  Madsen  et  al.  (1988)  should  be  activated. 

lknJ  Equivalent  roughness  length  scale  of  the  bottom.  Default:  [kn]  =  0.05  m. 

Note  that  [kn]  is  allowed  to  vary  over  the  computational  region.  In  that  case, 
use  the  commands  INPGRID  FRICTION  and  READINP  FRICTION  to  define 
and  read  the  friction  data.  This  command  FRICTION  is  still  required  to 
define  the  type  of  friction  expression.  The  value  of  [kn]  in  this  command  is 
then  not  required  (it  will  be  ignored). 


4.12.9.6  TRIAD 

TRIAD  [trfac]  [cutfr] 


TRAID  allows  the  user  to  activate  the  triad  wave-wave  interactions  in  the  SWAN  model  (see 

Section  5.1). 

[trfac]  The  value  proportionality  coefficient.  Default:  [trfac]  =0.1. 

[cutfr]  Controls  the  maximum  frequency  that  is  considered  in  the  triad  computations. 

The  value  of  [cutfr]  is  the  ratio  of  this  maximum  frequency  over  the  mean 
frequency.  Default:  [cutfr]  =  2.2. 
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4.12.9.7  OBSTACLE 


TRANSM  [trcoef]  | 

OBSTACLE  <  >  (REFL  [reflc])  LINE  <  [xp]  [yp] 

|  DAM  [hgt]  [alpha]  [beta]  | 


With  this  optional  command  the  user  provides  the  characteristics  of  a  (line  of)  sub-grid  obstacle(s) 
through  which  waves  are  transmitted  or  against  which  waves  are  reflected  (possibly  both  at  the 
same  time).  Reflection  is  only  spectral  reflection.  The  obstacle  is  sub-grid  in  the  sense  that  it  is 
narrow  compared  to  the  spatial  meshes.  Its  length  should  be  at  least  one  mesh  length. 

The  location  of  the  obstacle  is  defined  by  a  sequence  of  comer  points  of  a  line.  The  obstacles 
interrupt  the  propagation  of  the  waves  from  one  grid  point  to  the  next  wherever  the  obstacle  line  is 
located  between  two  neighboring  grid  points.  The  resolution  of  the  obstacle  is  therefore  equal  to  the 
computational  grid  spacing.  In  order  for  an  obstacle  to  be  effective  it  must  be  located  such  that  it 
crosses  at  least  one  grid  line.  This  is  always  the  case  when  an  obstacle  is  larger  than  one  mesh 
length. 

The  computation  of  transmission  and  reflection  is  problematic  if  an  obstacle  runs  exactly  through 
one  or  more  grid  points.  SWAN  will  move  the  obstacle  over  a  small  distance  (0.01  of  the  mesh 
size)  if  this  occurs.  The  reflection  results  will  be  incorrect  if  more  than  one  obstacle  crosses  the 
same  grid  line  between  two  neighboring  grid  points.  SWAN  is  not  able  to  detect  this  so  the  user 
must  check  that  the  model  fulfills  this  condition.  The  command  is  NOT  used  for  1-D  mode. 


The  obstacle  locations  may  be  plotted  with  option  LINES  in  the  PLOTGEOGR  command 
(providing  isoline  plots  or  vector  plots). 

TRANSM  With  this  option  the  user  indicates  that  the  transmission  coefficient  is  a 

constant. 


[trcoef]  Constant  transmission  coefficient  formulated  in  terms  of  wave  height,  i.e. 

ratio  of  transmitted  significant  wave  height  over  incoming  significant  wave 
height.  Default:  [trcoef]  =  0.0  (no  transmission  =  complete  blockage) 

DAM  With  this  option  the  user  indicates  that  the  transmission  coefficient  depends 

on  the  incident  wave  conditions  at  the  obstacle  and  on  the  obstacle  height, 
which  may  be  submerged  (see  Section  5.1). 

[hgt]  The  elevation  of  the  top  of  the  obstacle  above  reference  level,  which  is  the 

same  reference  level  as  for  bottom.  Use  a  negative  value  if  the  top  is  below 
that  reference  level.  This  value  is  required  if  OBSTACLE  is  used. 


67 


SWAN  User’s  Manual 


[alpha],  [beta] 


REFL 


[reflc] 


LINE 
[xp],  [yp] 


Coefficients  determining  the  transmission  coefficient  (see  Section 
5.1).  Default:  [alpha]  =  2.6  and  [beta]  =0.15. 

If  this  keyword  is  present  the  obstacle  will  reflect  wave  energy,  possibly  in 
combination  with  transmission.  Reflections  will  be  computed  only  if  the 
spectral  directions  cover  the  full  360°,  i.e.,  if  in  the  command  CGRID  the 
option  CIRCLE  is  activated. 

Constant  reflection  coefficient,  formulated  in  terms  of  wave  height,  i.e.  the 
ratio  of  reflected  significant  wave  height  over  incoming  significant  wave 
height,  [reflc]  must  be  >=  0  and  <=  1.  Default:  [reflc]  =  1,  if  the  keyword 
REFL  is  present. 

With  this  required  keyword  the  user  defines  the  location  of  the  obstacle(s). 

Coordinates  of  a  comer  point  of  the  line  that  defines  the  location  of  the 
obstacle(s)  (if  Cartesian  coordinates  are  used  in  m,  if  spherical  coordinates 
are  used  in  degrees,  see  command  CGRID,  Section  4.12.4.4),  At  least  two 
corner  points  must  be  provided. 


Note:  On  plotting  near  obstacles:  see  Section  4.13.2  on  plot  output. 


4.12.9.8  SETUP 

SETUP  [supcor] 


If  this  optional  command  is  given,  the  wave-induced  set-up  is  computed  and  accounted  for  in  the 
wave  computations,  and  during  the  computation  it  is  added  to  the  depth  that  is  obtained  from  the 
READ  BOTTOM  and  READ  WLEVEL  commands. 

[supcor]  By  default  the  wave-induced  setup  is  computed  with  an  added  constant  such 

that  the  setup  is  zero  in  the  deepest  point  of  the  model  grid.  The  user  can 
modify  the  constant  by  the  value  of  [supcor].  The  user  can  thus  impose  a 
setup  in  any  one  point  (and  only  one)  in  the  grid  by  first  running  SWAN, 
then  reading  the  setup  in  that  point  and  adding  or  subtracting  the  required 
value  of  [supcor]  (in  m;  positive  if  the  setup  has  to  rise). 

Default:  [supcor]  =  0. 
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4.12.9.9 

OFF 

|  WINDGROWTH 

i 

I 

1 

1 OUADRUPL 

1 

1 

| 

1 

|  WCAPPING 

1 

OFF 

< 

> 

|  BREAKING 

i 

1 

1 

|  REFRAC 

I 

1 

i 

1 

1 

(FSHIFT 

I 

1 

i 

1 

1 

1 BNDCHK 

i 

With  this  optional  command  the  user  can  change  the  default  inclusion  of  various  physical 
processes.  This  command  is  recommended  for  research  purposes  and  not  for  operational  use. 

WINDGROWTH  Switches  off  wind  growth  (in  commands  GEN1,  GEN2  and  GEN3). 


QUADRUPL  Switches  off  quadruplet  wave-wave  interactions  (in  command  GEN3). 

WCAPPING  Switches  off  whitecapping  (in  command  GEN3). 


BREAKING 

REFRAC 

FSHIFT 

BNDCHK 


Switches  off  depth-induced  breaking  dissipation.  Caution:  wave  heights  may 
diverge  in  very  shallow  water. 

Switches  off  refraction  (action  transport  in  0-direction). 

Switches  off  frequency  shifting  in  frequency  space  (action  transport  in  a- 
space). 

Switches  off  the  checking  of  the  difference  between  imposed  and  computed 
significant  wave  height  at  the  boundary  of  the  computational  grid  (see  also 
command  SET,  Section  4.12.4.2), 
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4.12.10  Numerics 


4.12.10.1  PROP 


PROP 

|  BSBT 

< 

|  SEC 

1 

1  | 

|  GSE  [waveage] 

<  MIN 

>  | 

1 

|  HR 

1  1 

1 

|  DAY 

1  1 

The  PROP  command  is  used  for  choosing  (a)  the  BSBT  scheme,  used  for  stationary  and 
nonstationary  computations,  (b)  the  default  S&L  scheme  (nonstationary)  or  the  default  SORDUP 
scheme  (stationary  cases),  or  (c)  the  wave  age,  for  the  default  nonstationary  S&L  scheme.  With 
computational  nonstationary  S&L,  if  the  run  time  limitations  require  CFL  »1  for  the  dominant 
wave  period,  BSBT  is  recommended  rather  than  the  default  S&L. 

BSBT  The  BSBT  scheme  will  be  used  in  the  computations. 

GSE  Garden-sprinkler-effect  is  to  be  counteracted  in  the  S  and  L  propagation 

scheme  (default  for  nonstationary  computations)  by  adding  a  diffusion  term  to 
the  basic  equation.  This  may  affect  the  numerical  stability  of  SWAN  (see 
Section  5.2). 

[waveage]  The  time  interval  used  to  determine  the  diffusion,  which  counteracts  the  so- 

called  garden-sprinkler  effect.  The  default  value  of  [waveage]  equals  zero,  or 
no  added  diffusion.  The  value  of  [waveage]  should  correspond  to  the  travel 
time  of  the  waves  over  the  computational  region. 

Note:  All  schemes  can  be  used  in  combination  with  curvilinear  grids.  With  the  higher  order 
schemes  (S&L  and  SORDUP)  it  is  important  to  use  a  gradually  varying  grid,  otherwise  there  may 
be  a  severe  loss  of  accuracy.  If  sharp  transitions  in  the  grid  cannot  be  avoided  it  is  safer  to  use  the 
BSBT  scheme. 

4.12.10.2  NUMERIC 


NUMERIC 


(  ACCUR  [drel]  [dhoval]  [dtoval]  [npnts] 

(  DIRIM  PL  [cdd]  [cdlim] 

(  SIGIMPL  [css]  [prec]  [epsl]  [eps2]  Joutp] 
(  SETUP  [prec]  [eps2]  [outp]  [niter] 


|  ->  STAT  [mxitst]  | 

<  >  [limiter]  ) 

|  NONSTAT  [mxitns]  | 

) 

[niter]  ) 

) 


& 

& 

& 
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This  optional  command  allows  the  user  to  influence  some  numerical  properties  of  SWAN. 

ACCUR  Influences  the  criterion  for  terminating  the  iterative  procedure  in  the  SWAN 

computations  (both  stationary  and  nonstationary  mode).  SWAN  terminates  the 
iterations  if: 

a)  The  change  in  the  local  significant  wave  height  (Hs)  from  one  iteration  to 
the  next  is  less  than 

(1)  fraction  [drel]  of  that  height  or 

(2)  fraction  [dhoval]  of  the  average  significant  wave  height  (average 
over  all  wet  grid  points). 

And 

b)  The  change  in  the  local  mean  wave  period  ( RPER  =  RTmo\)  from  one 
iteration  to  the  next  is  less  than 

(1)  fraction  [drel]  of  that  period  or 

(2)  fraction  [dtoval]  of  the  average  mean  wave  period  (average  over  all 
wet  grid  points). 

And 

c)  Conditions  (a)  and  (b)  are  fulfilled  in  more  than  fraction  [npnts]%  of  all 
wet  grid  points. 

[drel]  Default  [drel]  =  0.02  [-]. 

[dhoval]  Default  [dhoval]  =  0.02  [-]. 

[dtoval]  Default  [dtoval]  =  0.02  [-]. 

[npnts]  Default  [npnts]  =  98.  [-]. 

STAT  The  maximum  number  of  iterations  in  a  stationary  computation. 

[mxitst]  The  maximum  number  of  iterations  for  stationary  computations.  The 

computation  stops  when  this  number  is  exceeded.  Default  [mxitst]  =  15.  Note 
that  [mxitst]  can  be  set  to  0  if  one  wants  to  check  the  input  to  the  model 
without  making  computations. 

NONST  The  maximum  number  of  iterations  per  time  step  in  a  nonstationary 

computation. 

[mxitns]  The  maximum  number  of  iterations  per  time  step  for  nonstationary 

computations.  The  computation  moves  to  the  next  time  step  when  this  number 
is  exceeded.  Default:  [mxitns]  =  1 .  Note  that  [mxitns]  can  be  set  to  zero  if  one 
wants  to  check  the  input  to  the  model  without  making  computations. 
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[limiter] 


DIRIMPL 

[cdd] 


[cdlim] 


SIGIMPL 


SETUP 


[css] 


[prec] 


Determines  the  maximum  change  per  iteration  (stationary  and  nonstationary 
runs;  note  that  default  one  iteration  equals  one  upgrade  is  used  per  time  step) 
of  energy  density  per  spectral  (a,0)-bin  in  terms  of  a  fraction  of  the  omni¬ 
directional  Phillips  level  (Section  5.1).  Default:  [limiter]  =0.1.  If  command 
OFF  QUAD  is  used,  then  SWAN  deactivates  the  limiter. 

This  option  is  used  to  influence  the  numerical  scheme  for  refraction. 

A  value  of  [cdd]  =  0  corresponds  to  a  central  scheme  and  has  the  largest 
accuracy  (diffusion  ~  0)  but  the  computation  may  more  easily  generate  spurious 
fluctuations.  A  value  of  [cdd]  =  1  corresponds  to  an  upwind  scheme  and  it  is 
more  diffusive  and  therefore  preferable  if  (strong)  gradients  in  depth  or  current 
are  present.  Default:  [cdd]  =  0.5. 

If  the  spatial  discretization  of  the  bathymetry  or  the  currents  is  too  coarse,  the 
waves  may  turn  too  far  (more  than  90  degrees,  say)  over  one  spatial  grid  step. 
The  computational  results  will  then  be  very  inaccurate.  In  such  a  case  SWAN 
can  limit  the  maximum  turning  of  the  waves  over  one  spatial  grid  to  90  degrees 
to  obtain  robust  (but  not  necessarily  correct)  results. 

<  0  Then  no  limiter  is  used  (this  is  default). 

=  0  Refraction  is  off  (same  effect  as  command  OFF). 

=  4  Waves  turning  limited  to  about  90  degrees  over  one  spatial  grid  step. 

Controls  the  accuracy  of  computing  the  frequency  shifting.  The  type  of 
preconditioning,  required  accuracy  to  terminate  the  iteration  ([epsl]  and 
[eps2]),  the  amount  of  required  output  and  maximum  number  of  iterations  of 
the  linear  iterative  ILU-CGSTAB  solver  (used  in  the  computations  in  the 
presence  of  currents  or  time  varying  depth)  can  be  chosen  by  the  user. 

Controls  the  accuracy  of  computing  the  wave-induced  setup.  Type  of 
preconditioning,  required  accuracy  to  terminate  the  iteration  ([eps2]),  the 
amount  of  required  output  and  maximum  number  of  iterations  of  the  linear 
iterative  ILU-CGSTAB  solver  can  be  chosen  by  the  user. 

A  value  of  [css]  =  0  corresponds  to  a  central  scheme  and  has  the  largest 
accuracy  (diffusion  0)  but  the  computation  may  more  easily  generate  spurious 
fluctuations.  A  value  of  [css]  =  1  corresponds  to  an  upwind  scheme  and  it  is 
more  diffusive  and  therefore  preferable  if  (strong)  gradients  in  the  currents  are 
present.  Default:  [css]  =  0.5. 

Value  for  preconditioner  of  the  ILU-CGSTAB  solver  (see  Section  5.2) 

=  0  No  preconditioner. 

=  -1  Diagonal  preconditioner. 

=  -3  ILU  preconditioner. 

=  3  Default  [prec]  (most  robust  option  regarding  the  preconditioner). 
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[eps  1  ]  [eps2]  Criterion  to  terminate  the  iterative  solver.  The  criterion  is  based  on: 

| ANk -b\\2  <[eps\}  +  [eps2]\ANk_x  - b\\2  +  [epsl]^ 

Where  A  is  a  matrix,  N  is  the  action  density,  b  is  the  right  hand  vector,  k  is  the 
iteration  number,  (in  case  of  the  SETUP  option,  [epsl]  =  0. 

Defaults:  [epsl]  =  l.e-6  and  [eps2]  =  l.e-4 

[outp]  Output  for  ELU-CGSTAB  solver. 

=  0  No  output. 

=  1  Additional  information  about  the  iteration  process  is  written  to  the  print 
file. 

=  2  Gives  a  maximal  amount  of  output  concerning  the  iteration  process. 
Default  =  0. 

[niter]  Maximum  number  of  iterations  for  the  ILU-CGSTAB  solver  (per  geographic 

grid  point).  Default  [niter]  =  20. 

4.13  Output  Commands 

There  are  two  categories  of  output  commands,  each  with  two  classes: 

1 .  Locations 

la.  Commands  defining  sets  of  output  locations  at  which  the  user  requires  output.  Each  set 
is  indicated  with  a  name  ('sname'  in  this  manual)  which  must  be  unique  and  not  more 
than  eight  characters  long. 

Types  of  sets  of  output  points: 

FRAME  To  define  a  set  of  output  locations  on  a  regular  grid. 

GROUP  To  define  a  set  of  output  locations  on  a  regular  or  curvilinear  grid. 

CURVE  To  define  a  set  of  output  locations  along  a  curve. 

RAY  To  define  a  set  of  output  locations  along  a  depth  or  bottom  contour 

line  (with  ISOLINE). 

ISOLINE  To  define  a  set  of  output  locations  along  a  depth  or  bottom  contour 

line  (with  RAY). 

POINTS  To  define  a  set  of  isolated  output  locations. 

NGRID  To  define  a  set  of  output  locations  for  a  nested  grid  to  be  used  in  a 

subsequent  SWAN  run. 

Commands  FRAME,  GROUP,  RAY,  ISOLINE  and  NGRID  cannot  be  used  in  1-D 
mode.  If  one  gives  one  name  for  two  sets  of  output  locations,  the  first  set  is  lost  (first  in 
the  sequence  in  the  command  file).  SWAN  reserves  three  special  types  (BOTTGRID, 
CGRID  and  TESTPNTS)  for  use  (see  below),  but  the  user  may  not  define  sets  with 
these  names. 

lb.  Commands  defining  additional  geographical  information  to  be  used  in  plot  output: 
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LINE  Defines  a  line  to  indicate  coastlines  or  contours  of  a  certain  object. 

LINE  can  be  used  in  a  plot  generated  with  command  PLOTGEOGR. 
SITES  Plot  (geographic)  names  in  a  plot  generated  with  command 

PLOTGEOGR. 

Commands  LINE  and  SITES  cannot  be  used  in  1-D  mode. 


2. 


Write  /  plot 

2a.  Commands  defining  data  file  output  (write)  at  the  above  defined  set(s)  of  output 
locations: 


BLOCK 

TABLE 

SPECOUT 

NESTOUT 


Write  spatial  distributions  (only  for  FRAME  and  GROUP). 

Write  output  for  (set  of)  output  location(s). 

Write  to  data  file  the  variance  /  energy  (see  command  SET,  Section 
4.12.4.2)  density  spectrum  for  (set  of)  output  location(s). 

Write  to  data  file  two-dimensional  action  density  spectra  (relative 
frequency)  along  the  boundary  of  a  nested  grid  (see  command  NGRID, 
Section  4.13.1.7)  to  be  used  in  a  subsequent  SWAN  run. 


Commands  BLOCK  and  NESTOUT  cannot  be  used  in  1-D  mode 


2b.  Commands  defining  plot  output  at  the  above  defined  sets  of  output  locations  (and 

auxiliary  plot  output): 

PLOTGEOGR  A  plot  of  a  spatial  distribution  is  required  (contour  line  plot  and  /  or 
vector  plot). 

PLOTSTAR  Show  the  directional  distribution  of  the  action  transport. 

PLOTPP  Show  the  locations  of  points  where  the  problems  occur  (problem 

points). 

PLOTSPEC  Polar  plot  of  a  2-D  variance/energy  density  spectrum,  for  (a  set)  of 
output  location(s). 

Commands  PLOTGEOGR,  PLOTSTAR  and  PLOTPP  cannot  be  used  in  1-D  mode. 

Note.  The  plot  output  of  the  model  is  not  adapted  to  obstacles.  For  the  plot,  computational  results 
may  be  interpolated  from  points  at  both  sides  of  the  obstacle.  Results  for  output  points  near  an 
obstacle  must  therefore  be  interpreted  with  caution.  The  effect  is,  for  instance,  that  the  isolines  of 
the  wave  height  near  the  obstacle  appear  rather  "ragged". 


4.13.1  Output  Location  Commands 

4.13.1.1  FRAME 

FRAME  ’sname'  [xpfr]  [ypfr]  [alpfr]  [xlenfr]  [ylenfr]  [mxfr]  [myfr])  ([scale]) 

With  this  optional  command  the  user  defines  output  on  a  rectangular  grid  in  a  regular,  rectangular 
frame.  FRAME  cannot  be  used  in  1-D  mode. 
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If  the  set  of  output  locations  is  identical  to  a  part  of  the  computational  grid,  then  the  user  can  use  the 
alternative  command  GROUP. 

'sname'  Name  of  the  frame  defined  by  this  command. 

[xpfr]  X-coordinate  of  the  origin  of  the  frame  in  problem  coordinates.  Cartesian 

coordinate  units  are  in  m  and  spherical  coordinate  units  are  in  degrees  (see 
command  COORD,  Section  4.12.4.4), 

[ypfr]  Y-coordinate  of  the  origin  of  the  frame  in  problem  coordinates.  Cartesian 

coordinate  units  are  in  m  and  spherical  coordinate  units  are  in  degrees  (see 
command  COORD,  Section  4.12.4.4). 

[alpfr]  Direction  of  the  x-axis  of  the  frame,  in  degrees  for  Cartesian  convention,  and 

[alpfr]  must  be  zero  in  case  of  spherical  coordinates). 

[xlenfr]  Length  of  the  frame  in  x-direction.  Cartesian  coordinate  units  are  in  m  and 

spherical  coordinate  units  are  in  degrees  (see  command  COORD,  Section 
4.12.4.4). 

[ylenfr]  Length  of  the  frame  in  y-direction.  Cartesian  coordinate  units  are  in  m  and 

spherical  coordinate  units  are  in  degrees  (see  command  COORD,  Section 
4.12.4.4). 

[mxfr]  Number  of  meshes  in  x-direction  of  the  rectangular  grid  in  the  frame  (one  less 

than  the  number  of  grid  points  in  this  direction).  Default:  [mxf]  =  20. 

[myfr]  Number  of  meshes  in  y-direction  of  the  rectangular  grid  in  the  frame  (one  less 

than  the  number  of  grid  points  in  this  direction).  Default:  [myf]  =  20. 

[scale]  Controls  the  horizontal  scale  of  plotting  (if  plotting  is  required):  length  in  cm  on 

paper  per  m  or  degree  in  reality.  Default:  Plot  as  large  as  possible  within  size  of 
18  x  24  cm2  (x-  and  y-direction  respectively). 

Some  output  may  be  required  on  a  frame  that  is  identical  with  the  input  (bottom/current)  grid  or 
with  the  computational  grid  (e.g.,  for  test  purposes  or  to  avoid  interpolation  errors  in  the  output). 
These  frames  need  not  be  defined  when  using  the  FRAME  command.  The  frames  are  always 
generated  automatically  by  SWAN  under  the  names  'sname'  =  'BOTTGRID'  (for  the  bottom/current 
grid)  and  'sname'  =  'CGRID'  (for  the  computational  grid). 

4.13.1.2  GROUP 

GROUP  'sname'  SUBGRID  [ixl]  [ix2]  [iyl]  [iy2] 
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With  this  optional  command  the  user  defines  a  group  of  output  locations  on  a  rectangular  or 
curvilinear  grid  that  is  identical  to  (part  of)  the  computational  grid  (rectilinear  or  curvilinear). 
GROUP  may  be  convenient  for  use  in  obtaining  output  that  is  not  affected  by  interpolation  errors, 
which  would  occur  when  an  output  grid  is  used  that  is  not  identical  with  (part  of)  the  computational 
grid. 

GROUP  cannot  be  used  in  1-D  mode. 

Note:  SWAN  cannot  generate  geographical  plots  for  GROUP  on  a  curvilinear  computational  grid 
(see  command  PLOTGEOGR,  Section  4.13.2.6). 

Command  CGRID  should  precede  command  GROUP.  The  subgrid  contains  those  points  (ix,  iy)  of 
the  computational  grid  for  which: 

[ix  1  ]  <=  ix  <=  [ix2]  and  [iy  1  ]  <=  iy  <=  [iy2]  . 

For  convenience  the  size  of  the  group,  the  corner  coordinates  and  the  angle  with  the  problem 
coordinate  system  are  written  to  print  file.  The  origin  of  the  computational  grid  is  (ix  =  0,  iy  =  0). 

sname  Name  of  the  set  of  output  locations  defined  by  this  command. 

[ixl]  Lowest  grid  index  of  subgrid  in  terms  of  computational  grid  in  ix-direction. 

[iyl]  Lowest  grid  index  of  subgrid  in  terms  of  computational  grid  in  iy-direction. 

[ix2]  Highest  grid  index  of  subgrid  in  terms  of  computational  grid  in  ix-direction. 

[iy2]  Highest  grid  index  of  subgrid  in  terms  of  computational  grid  in  iy-direction. 


Limitations:  [ixl]  >-  0,  [ix2]  <-  [mxc],  [iyl]  >=  0,  [iy2]  <=  [myc]  ([mxc]  and  [myc]  as  defined  in 
the  command  CGRID). 


4.13.1.3  CURVE 

CURVE  'sname'  [xpl]  [ypl]  <  [int]  [xp]  [yp]  > 


With  the  optional  command  CURVE,  the  user  defines  output  along  a  curved  line.  The  curve  is 
actually  a  broken  line,  defined  by  the  user  with  its  corner  points.  The  values  of  the  output  quantities 
along  the  curve  are  interpolated  from  the  computational  grid.  This  command  may  be  used  more 
than  once  to  define  more  curves. 

'sname1  Name  of  the  curve. 
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[xpl],  [ypl] 


[int] 


[xp],  [yp] 


Problem  coordinates  of  the  first  point  of  the  curve.  If  Cartesian  coordinates  are 
used,  the  units  are  in  m.  If  spherical  coordinates  are  used,  the  units  are  in 
degrees  (see  command  COORD,  Section  4.12.4.4), 

SWAN  will  generate  output  at  [int]-l  equidistant  locations  between  two 
subsequent  comer  points  of  the  curve  (including  the  two  comer  points  of  the 
curve). 

Problem  coordinates  of  a  comer  point  of  the  curve.  Repeat  the  group  [int]  [xp] 
[yp]  in  proper  order  if  there  are  more  comer  points  on  the  curve. 


4.13.1.4  RAY 


RAY  'mame'[xpl]  [ypl]  [xql]  [yql]  & 

<  [int]  [xp]  [yp]  [xq]  [yq]  > 


RAY  is  an  optional  command  with  which  the  user  provides  SWAN  with  information  to  determine 
output  locations  along  the  depth  contour  line(s)  defined  subsequently  in  command  ISOLINE  (see 
below).  The  model  determines  the  locations  as  the  intersections  of  the  depth  contour  line(s)  and  the 
set  of  straight  rays  defined  by  command  RAY.  These  rays  are  characterized  by  a  set  of  master  rays 
defined  by  their  start  and  end  positions  ([xp],  [yp])  and  ([xq],  [yq]).  Between  each  pair  of 
sequential  master  rays  SWAN  generates  [int]-l  intermediate  rays  by  linear  interpolation  of  the  start 
and  end  positions. 


Note:  The  rays  defined  here  are  not  synonymous  with  wave  rays  (e.g.  as  obtained  from 
conventional  refraction  computations). 


’mame’ 

[xpl],  [ypl] 
[xql],  [yql] 

[int] 


[xp] ,  [yp]; 

[xq] ,  [yq] 


Name  of  the  set  of  rays  defined  by  this  command. 

Problem  coordinates  of  the  begin  and  end  points  of  the  first  master  ray. 


Number  of  subdivisions  between  the  previous  master  ray  and  the  following 
master  ray  defined  by  the  following  data  (number  of  subdivisions  is  one  more 
than  the  number  of  interpolated  rays). 

Problem  coordinates  of  the  begin  and  end  points  of  each  subsequent  master 
ray.  For  Cartesian  coordinates  the  units  are  m  and  for  spherical  coordinates 
the  units  are  degrees  (see  command  COORD,  Section  4.12.4.4). 


RAY  cannot  be  used  in  1-D  mode. 
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4.13.1.5  ISOLINE 


1  ->  DEPTH 

ISOLINE  'sname'  'marne'  < 

|  BOTTOM 


>  [dep] 


With  this  optional  command  the  user  defines  a  set  of  output  locations  along  one  depth  or  bottom 
level  contour  line  (in  combination  with  command  RAY). 

sname  Name  of  the  set  of  output  locations  defined  by  this  command. 

'mame’  Name  of  the  set  of  rays  (as  defined  in  command  RAY). 

[dep]  The  depth  (in  m)  of  the  depth  contour  line  along  which  SWAN  generates  output 

locations.  If  the  keyword  DEPTH  appears  in  front  of  the  value  the  true  depth  is 
used,  if  the  keyword  BOTTOM  appears  the  water  level  is  ignored,  i.e.  the  depth 
with  respect  to  datum  level  is  used. 

The  set  of  output  locations  along  the  depth  contour  lines  created  with  this  command  is  of  the  type 
CURVE. 

ISOLINE  cannot  be  used  in  1-D  mode. 


4.13.1.6  POINTS 


I  <  Up]  [yp]  >  | 

POINTS  'sname'  < 

|  FILE  'fname'  | 


With  this  optional  command  the  user  defines  a  set  of  individual  output  locations  (points).  The 
coordinates  of  these  points  are  given  in  the  command  itself  or  read  from  a  file  (option  FILE). 

'sname'  Name  of  the  points. 

[xp],  [yp]  Problem  coordinates  of  one  output  location. 

If  Cartesian  coordinates  are  used,  the  units  are  in  m. 

If  spherical  coordinates  are  used,  the  units  are  degrees  (see  command 
COORD,  Section  4.12.4.4), 
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4.13.1.7  NGRID _ 

NGRID  'sname'  [xpn]  [ypn]  [alpn]  [xlenn]  [ylenn]  [mxn]  [myn] 


NGRID  cannot  be  used  in  1-D  mode. 

If  the  user  wishes  to  carry  out  nested  SWAN  run(s)  a  separate,  coarse-grid  SWAN  run  is  required. 
With  this  optional  command  NGRID,  the  user  defines  in  the  present  coarse-grid  run  a  set  of  output 
locations  along  the  boundary  of  the  subsequent  nested  computational  grid.  The  set  of  output 
locations  thus  defined  is  of  the  type  NGRID. 

Command  NESTOUT  is  required  after  NGRID  to  generate  some  data  for  the  (subsequent)  nested 
run.  Commands  BLOCK  and  PLOT. . .  are  not  used  because  a  set  of  locations  of  the  type  NGRID 
does  not  represent  a  geographic  region,  only  its  outline. 

'sname'  Name  of  the  set  of  output  locations  along  the  boundaries  of  the  following 

nested  computational  grid  defined  by  this  command. 

[xpn]  Geographic  location  of  the  model  grid  origin  of  the  coarse-grid  run  in  the 

problem  coordinate  system  (x-coordinate).  If  Cartesian  coordinates  are  used,  the 
units  are  m.  If  spherical  coordinates  are  used,  the  units  are  degrees  (see 
command  COORD,  Section  4.12.4.4). 

[ypn]  Geographic  location  of  the  model  grid  origin  of  the  coarse-grid  run  in  the 

problem  coordinate  system  (y-coordinate).  If  Cartesian  coordinates  are  used,  the 
units  are  m.  If  spherical  coordinates  are  used,  the  units  are  degrees  (see 
command  COORD,  Section  4.12.4.4). 

[alpn]  Direction  of  the  positive  x-axis  of  the  computational  grid  of  this  coarse-grid  run 

(in  degrees,  Cartesian  convention). 

[xlenn]  Length  in  the  x-direction  of  the  nested  grid  If  Cartesian  coordinates  are  used, 

the  units  are  m.  If  spherical  coordinates  are  used,  the  units  are  degrees  (see 
command  COORD,  Section  4.12.4.4). 

[ylenn]  Length  in  y-direction  of  the  nested  grid.  If  Cartesian  coordinates  are  used,  the 

units  are  m.  If  spherical  coordinates  are  used,  the  units  are  degrees  (see 
command  COORD,  Section  4.12.4.4). 

[mxn]  Number  of  meshes  of  the  output  grid  in  the  x-direction  of  this  grid  (this  number 

is  one  less  than  the  number  of  grid  points  in  this  direction),  [mxn]  does  not 
have  to  be  equal  to  the  number  of  meshes  in  the  nested  computation,  as  SWAN 
will  interpolate  the  required  information.  Default:  [mxn]  is  chosen  such  that  the 
mesh  size  of  the  output  grid  is  roughly  equal  to  the  mesh  size  of  the  coarse  grid, 
but  at  least  one. 
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[myn]  Number  of  meshes  of  the  output  grid  in  the  y-direction  of  this  grid  (this  number 

is  one  less  than  the  number  of  grid  points  in  this  direction),  [myn]  does  not 
have  to  be  equal  to  the  number  of  meshes  in  the  nested  computation,  as  SWAN 
will  interpolate  the  required  information.  Default:  [myn]  is  chosen  such  that  the 
mesh  size  of  the  output  grid  is  (roughly)  equal  to  the  mesh  size  of  the  coarse 
grid,  but  at  least  one. 

If  the  user  wishes  to  view  the  location  of  the  nested  grid,  e.g.  in  relation  to  the  bathymetry  in  the 
computational  region  of  the  coarse  run  (e.g.  defined  by  'sname'  =  'CGRID'),  the  command 

PLOTGEOGR  should  be  used.  If  the  name  of  the  nested  grid  is  'sname'  =  'NG',  the  syntax  should 
be: 

PLOTGEOGR  CGRID  ISO  BOTTOM  LOCATION  'NG'  (see  command  PLOTGEOGR 
Section  4.13.2.6), 


4.13.1.8  LINE 


I  ->  CONTINUOUS  | 

:  >  (COLOR  [ipen])  <  [xp]  [yp]  > 

|  DASHED  [pat]  [len]  |  | 


With  this  optional  command  the  user  defines  a  line  that  is  plotted  with  option  LINES  (see  the 
PLOT...  commands  in  Section  4.13.2).  The  line  is  defined  by  the  comer  points  of  a  sequence  of 
straight  lines.  LINE  is  provided  to  facilitate  orientation  on  the  plots.  One  can  indicate  coastlines, 
contours  of  certain  landmarks,  etc.  The  command  LINE  may  be  repeated. 

CONT  Indicates  the  type  of  line  will  be  a  continuous  line. 

DASH  A  dashed  line  will  be  drawn. 

[pat]  Pattern  type  number  (integer).  Default:  [pat]  =  3. 

Hen]  Pattern  length  in  cm  (real).  Default:  [len]  =  1. 

COLOR  To  be  used  if  a  color  other  than  black  is  desired. 

[ipen]  Color  number  (integer).  Default:  [ipen]  =  2. 

fxp]»  [yp]  Coordinates  of  a  comer  point  of  the  line  in  the  problem  coordinate  system.  If 

Cartesian  coordinates  are  used,  the  units  are  in  m.  If  spherical  coordinates  are 
used,  the  units  are  degrees  (see  command  COORD,  Section  4.12.4.4), 

LINE  cannot  be  used  in  1-D  mode. 


80 


SWAN  User’s  Manual 


4.13.1.9  SITES 


REGION  | 

SITES  <  'pname'  [xp]  [yp]  [size]  <  >  > 

I  TOWN  | 


SITES  is  an  optional  command  in  which  the  user  defines  names  of  towns,  regions  etc.,  that  can  be 
plotted  (with  option  SITES  in  command  PLOTGEOGR).  The  command  SITES  may  be  repeated. 

'pname'  The  name  of  a  town,  region  etc.,  with  a  maximum  16  characters  long. 

[xp],[yp]  X-  and  y-coordinates  of  the  location  where  the  name  must  be  plotted  in  the 

problem  coordinate  system.  If  Cartesian  coordinates  are  used,  the  units  are  in  m. 
If  spherical  coordinates  are  used,  the  units  are  degrees  (see  command  COORD, 

Section  4.12.4.4), 

[size]  The  size  of  the  characters  in  the  plot  (in  cm).  Default:  [size]  =  0.28  cm. 

REGION  The  name  is  plotted  with  the  point  of  reference  in  the  middle  of  the  name  (if 

space  allows).  This  is  intended  for  names  of  regions,  islands,  etc. 

TOWN  The  first  character  is  placed  at  the  point  of  reference  (if  space  allows).  This  is 

intended  for  names  of  towns,  etc. 

SITES  cannot  be  used  in  1  -D  mode. 

4.13.2  Write  or  Plot  Data  Commands 

For  definitions  of  output  parameters  see  Section  4.14. 

WARNING: 

When  integral  parameters  are  computed  by  the  user  from  the  output  spectrum  of  SWAN, 
differences  with  the  SWAN-computed  parameters  may  occur.  The  reasons  are: 

(a)  SWAN  accepts  at  the  boundaries  of  the  computational  grid  only  the  user-imposed 
incoming  wave  components,  and  it  replaces  the  user-imposed  outgoing  wave  components 
with  computed  components  (propagating  to  the  boundary  from  the  interior  region). 

(b)  During  the  computation  of  the  parameters,  SWAN  adds  an  analytical  (diagnostic)  high- 
frequency  tail  to  the  discrete  spectrum. 

(c)  SWAN  has  an  option  to  only  compute  within  a  pre-set  directional  sector  (pre-set  by  the 
user).  Wave  components  outside  this  sector  are  totally  ignored  by  SWAN  (no  additions  or 
replacements). 
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This  is  particularly  relevant  along  the  boundaries  of  SWAN  where  the  user-imposed  integral 
parameters  (boundary  conditions)  may  differ  from  the  SWAN-computed  parameters.  The  user  is 
informed  by  means  of  a  WARNING  in  the  output  print  file,  (see  Section  4.11.2.1)  when  the 
computed  significant  wave  height  differs  by  more  than  10%,  say,  from  the  user-imposed  significant 
wave  height  (command  BOUNDPAR2).  The  actual  value  of  this  difference  can  be  set  by  the  user 
(see  command  SET,  Section  4.12.4.2), 

It  should  be  noted  that  the  plot  output  of  the  model  is  not  adapted  to  obstacles.  For  the  plot, 
computational  results  may  be  interpolated  from  points  at  both  sides  of  the  obstacle.  Results  for 
output  points  near  an  obstacle  must  therefore  be  interpreted  with  caution.  The  effect  is  that  the 
isolines  of  the  wave  height  near  the  obstacle  appear  rather  "ragged". 


4.13.2.1  QUANTITY 


QUANTITY  <  >  'short' 'long' [lexp]  [hexp]  [excv] 


[power] 

(For  output  quantities  PER,  RPER  and  WLEN)  & 

[ref] 

(For  output  quantity  TSEC)  & 

[fswell] 

(For  output  quantity  HSWELL)  & 

|->  PROBLEMCOORD  | 

<  > 

[For  directions  (DIR,  TDIR,  PDIR) 

1  FRAME  | 

and  vectors  (FORCE,  WIND,  VELOCITY, 
TRANSPORT)} 

With  this  command  the  user  can  influence, 

(a)  the  naming  of  output  quantities, 

(b)  the  accuracy  of  writing  output  quantities, 

(c)  the  definition  of  some  output  quantities,  and 

(d)  reference  direction  for  vectors. 


The  output  parameters  are  the  same  as  in  command  BLOCK. 


User  preferred  short  name  of  the  output  quantity  (e.g.  the  name  appearing  in 
the  heading  of  a  table  written  by  SWAN).  If  this  option  is  not  used,  SWAN 
will  use  a  realistic  name. 
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'long'  Long  name  of  the  output  quantity  (e.g.  the  name  appearing  in  the  heading  of 

a  block  output  written  by  SWAN).  If  this  option  is  not  used,  SWAN  will 
use  a  realistic  name. 

[lexp]  Lowest  expected  value  of  the  output  quantity. 

[hexp]  Highest  expected  value  of  the  output  quantity.  The  highest  expected  value 

is  used  by  SWAN  to  determine  the  number  of  decimals  in  a  table  with 
heading.  The  QUANTITY  command  can  be  used  in  case  the  default 
number  of  decimals  in  a  table  is  unsatisfactory. 

[excv]  In  case  there  is  no  valid  value  (e.g.,  wave  height  in  a  dry  point),  this 

exception  value  of  the  output  quantity  is  written  in  a  table  or  block  output. 

The  following  data  are  accepted  only  in  combination  with  selected  output  quantities: 

[power]  Power  p  appearing  in  the  definition  of  PER,  RPER  and  WLEN  (see  Section 

4.14).  Note  that  the  value  for  [power]  given  for  PER  affects  also  the  value 
of  RPER.  The  power  for  WLEN  is  independent  of  that  of  PER  or  RPER. 
Default:  [power]  =  1. 

[ref]  Reference  time  used  for  the  quantity  TSEC.  Default:  Starting  time  of  the 

first  computation. 

[fswell]  Upper  limit  of  frequency  range  used  for  computing  the  quantity  HSWELL 

(see  Section  4.14).  Default:  [fswell]  =  0.1  Hz. 

PROBLEMCOORD  Vector  components  are  relative  to  the  x-  and  y-axes  of  the  problem 

coordinate  system  (see  command  COORD,  Section  4.12.4.4),  If  Cartesian 
direction  convention  is  used  directions  are  counter-clockwise  relative  to  the 
positive  x-axis  of  the  problem  coordinate  system  (see  command  SET, 
Section  4.12.4.2).  If  Nautical  direction  convention  is  used  the  directions  are 
relative  to  north  (clockwise;  see  command  SET,  Section  4.12.4.2). 

FRAME  If  output  is  requested  on  sets  created  by  command  FRAME  or  automatically 

(CGRID  (see  Section  4.12.6.1)  or  BOTTGRID  (see  Section  4.12.7.1)), 
vector  components  are  relative  to  the  x-  and  y-axes  of  the  frame  coordinate 
system  (see  command  FRAME,  Section  4.13.1.1).  If  Cartesian  direction 
convention  is  used  directions  are  counter-clockwise  relative  to  the  positive 
x-axis  of  the  problem  coordinate  system  (see  command  SET,  Section 
4.12.4.2).  If  Nautical  direction  convention  is  used  the  directions  are  relative 
to  north  (clockwise;  see  command  SET,  Section  4.12.4.2), 

Examples: 

QUANTITY  Xp  hexp  =100  $  for  simulations  of  lab  experiments. 
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QUANTITY  Hs  excv  =  -9. 

QUANTITY  Hswell  fswell  =  -0.08 
QUANTITY  Per  short  =  Tm- 1 ,0  '  power  =  0. 
QUANTITY  Transp  Frame 


$  to  change  the  exception  value  for  Hs. 
$  to  change  the  value  of  [fswell], 

$  to  redefine  average  wave  period. 

$  to  obtain  vector  components  and 
direction  with  respect  to  frame. 
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4.13.2.2  BLOCK 


| ->  HEADER 
BLOCK  'sname'  < 

|  NOHEADER 


HSIGN 

HSWELL 

DIR 

PDIR 

TDIR 

TM01 

RTM01 

RTP 

PER 

RPER 

TM02 

FSPR 

DSPR 

DEPTH 

VEL 

FRCOEF 

WIND 

DISSIP 

QB 

TRANSP 


>  [unit]  > 


>  'fname' (LAY-OUT  [idla]) 


(OUTPUT  [tbegblk]  [deltblk]) 


|  ->  SEC  | 
<  MIN  > 
I  HR  | 

|  DAY  | 
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FORCE 

UBOT 

IJRMS 

WLENGTH 

STEEPNESS 

DHSIGN 

DRTM01 

LEAK 

XP 

YP 

DIST 


BLOCK  cannot  be  used  in  1-D  mode.  BLOCK  indicates  that  one  or  more  spatial  distributions 
should  be  written  to  a  file. 


’sname’  Name  of  FRAME  or  GROUP  (see  command  FRAME  or  GROUP,  Sections 

4.13.1.1  or  4.13.1.2). 

HEADER  Indicates  that  the  output  should  be  written  to  a  file  with  header  lines.  The  text 

of  the  header  indicates  run  identification  (see  command  PROJECT,  Section 
4.12.4.1),  time,  frame  name  or  group  name  ('sname'),  variable  and  unit.  The 
number  of  header  lines  is  eight. 

NOHEADER  With  this  option  the  user  indicates  that  the  output  should  be  written  to  a  file 
without  header  lines. 


'fname' 


LAY-OUT 


Name  of  the  data  file  where  the  output  is  to  be  written  to. 

Default  for  option  HEADER  is  the  print  file  (see  Section  4.11.2.1).  In  case  of 
NOHEADER  the  filename  is  required. 

With  this  option  the  user  can  prescribe  the  layout  of  the  output  to  file  with  the 
value  of  [idla]. 


[idla] 


See  command  READINP  in  Section  4.12.7.2  (options  are  [idla]  =  1,3, 4). 
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Option  4  is  recommended  for  postprocessing  by  MATLAB.  Default  [idla]  =  1. 
For  definitions  of  the  output  quantities  (Hsign  etc.)  see  Section  4.14. 

Note:  For  output  on  (or  near)  a  boundary  of  the  computational  grid  or  near  an  obstacle,  see  the 
warning  at  the  introduction  of  this  section  (4.13.2), 

The  wave  parameters  in  the  SWAN  output  are  computed  from  the  wave  spectrum  over  the 
prognostic  portion  of  the  spectrum  with  the  diagnostic  tail  added.  This  value  may  therefore  deviate 
slightly  from  values  computed  by  the  user  from  the  output  spectrum  of  SWAN  not  containing  the 
diagnostic  tail. 

TIME  Time  for  which  the  values  on  the  same  line  are  valid.  Useful  only  in  case 

of  nonstationary  computations. 

HSIGN  Significant  wave  height  (in  m). 

HSWELL  Swell  wave  height  (in  m). 

DIR  Mean  wave  direction  for  Cartesian  convention  relative  to  the  x-axis  of  the 

problem  coordinate  system  (counter-clockwise  direction;  Cartesian  or 
Nautical  convention,  see  command  SET,  Section  4.12.4.2).  A  possible 
exception  occurs  in  the  case  of  output  with  BLOCK  command  in 
combination  with  command  FRAME  (see  command  QUANTITY, 

Section  4.13.2.1). 

PDIR  Peak  wave  direction  in  degrees  for  Cartesian  convention  relative  to  the  x- 

axis  of  the  problem  coordinate  system  (counter-clockwise).  A  possible 
exception  occurs  in  the  case  of  output  with  BLOCK  command  in 
combination  with  command  FRAME  (see  command  QUANTITY, 

Section  4.13.2.1). 

TDIR  Direction  of  energy  transport  in  degrees  for  Cartesian  convention  relative 

to  the  x-axis  of  the  problem  coordinate  system  (counter-clockwise).  A 
possible  exception  occurs  in  the  case  of  output  with  BLOCK  command  in 
combination  with  command  FRAME,  (see  command  QUANTITY, 

Section  4.13.2.1). 

TM01  Mean  absolute  wave  period  (in  s). 

RTM01  Mean  relative  wave  period  (in  s). 

RTP  Peak  period  (in  s)  of  the  variance  density  spectrum  (relative  frequency 

spectrum). 
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PER 

RPER 

TM02 

FSPR 

DSPR 

DEPTH 

VEL 

FRCOEF 

WIND 

DISSIP 

QB 

TRANSP 

FORCE 

UBOT 

URMS 

WLEN 

STEEPNESS 

DHSIGN 


Mean  absolute  wave  period  (in  s). 

Mean  relative  wave  period  (in  s). 

Mean  absolute  zero  crossing  period  (in  s). 

The  normalized  width  of  the  frequency  spectrum. 

Directional  spreading  of  the  waves  (in  degrees). 

Water  depth  (in  m)  (not  the  bottom  level!). 

Current  velocity  (in  m/s). 

Friction  coefficient  (equal  to  [cfw]  or  [kn]  in  command  FRICTION). 
Wind  velocity  (in  m/s). 

Energy  dissipation  due  to  bottom  friction,  wave  breaking  and 
whitecapping  (in  W/m2  of  m2/s,  depending  on  command  SET). 

Fraction  of  breaking  waves  due  to  depth-induced  breaking. 

Transport  of  energy  (vector;  W/m  or  m3/s,  depending  on  command  SET). 

Wave  induced  force  per  unit  surface  area  (vector;  in  N/m2). 

The  rms  value  of  the  maxima  of  the  orbital  velocity  near  the  bottom  (in 
m/s).  Output  only  if  command  FRICTION  is  used.  If  one  wants  to  output 
UBOT  with  friction  neglected  in  the  computations,  then  he/she  should  use 
the  command  FRICTION  with  the  value  of  the  friction  set  at  zero  e  g 
FRICTION  COLLINS  0. 

The  rms  value  of  the  orbital  velocity  near  the  bottom  (in  m/s).  If  one 
wants  to  output  UBOT  but  friction  is  to  be  neglected  in  the  computations, 
then  one  should  use  the  command  FRICTION  with  the  value  of  the 
friction  set  at  zero,  e.g.,  FRICTION  COLLINS  0. 

Average  wavelength  (in  m). 

Average  wave  steepness  (dimensionless). 

The  difference  in  significant  wave  height  as  computed  in  the  last  two 
iterations.  This  is  not  the  difference  between  the  computed  values  and  the 
final  limit  of  the  iteration  process.  It  is  at  most  an  indication  of  this 
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difference. 

DRTM01  The  difference  in  average  wave  period  (RTMOl)  as  computed  in  the  last 

two  iterations.  This  is  not  the  difference  between  the  computed  values 
and  the  final  limit  of  the  iteration  process.  It  is  at  most  an  indication  of 
this  difference. 

LEAK  Numerical  loss  of  energy  equal  to  across  boundaries  =  [dirl]  and  =  [dir2] 

of  a  directional  sector  (see  command  CGRID,  Section  4.12.6.1). 

XP  User  instructs  SWAN  to  write  the  x-coordinate  in  the  problem  coordinate 

system  of  the  output  location. 

YP  User  instructs  SWAN  to  write  the  y-coordinate  in  the  problem  coordinate 

system  of  the  output  location. 

DIST  If  output  has  been  requested  along  a  curve  (see  command  CURVE, 

Section  4.13.1.3)  then  the  distance  along  the  curve  can  be  obtained  with 
this  command  TABLE. 

Definition:  DIST  is  the  distance  along  the  curve  measured  from  the  first 
point  on  the  curve  to  the  output  location  on  the  curve  in  meters. 

[unit]  This  controls  the  scaling  of  output.  The  program  divides  computed  values 

by  [unit]  before  writing  to  file,  so  the  user  should  multiply  the  written 
value  by  [unit]  to  obtain  the  proper  value. 

Default  if  HEADER  is  selected,  value  is  written  as  a  five-position  integer. 
SWAN  takes  [unit]  such  that  the  largest  number  occurring  in  the  block 
can  be  printed. 

Default  if  NOHEADER  is  selected,  values  are  printed  in  floating-point 
format,  [unit]  =  1 . 

OUTPUT  The  user  requests  output  at  various  times.  If  the  user  does  not  use  this 

option,  the  program  will  give  BLOCK  output  for  the  last  time  step  of  the 
computation. 

[tbegblk]  Begin  time  of  output,  the  format  is: 


=  1 

ISO  notation 

19870530.153000 

=  2 

(as  in  HP  compiler): 

'30-May-87  15:30:00’ 

=  3 
=  4 
=  5 

(as  in  Lahey  compiler): 

05/30/87.15:30:00 

15:30:00 

87/05/30  15:30:00’ 

=  6 

as  in  WAM 

8705301530 

This  format  is  installation  dependent.  See  installation  manual  on  the 
SWAN  web  site.  Default  is  ISO. 
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[deltblk] 

SEC 

Time  interval  of  output,  the  unit  is  indicated  in  the  next  option. 

Unit  seconds. 

MIN 

Unit  minutes. 

HR 

Unit  hours. 

DAY 

Unit  days. 

4.13.2.3  TABLE 

|  ->HEADER  | 

TABLE  'sname' 

i  | 

<  NOHEADER  >  'fname' 

& 

|... 

<  < 

|... 

1  1 

|  INDEXED  j 

1  |  ->  SEC 

>  >  (OUTPUT  [tbegtbl]  [delttbl]  <  MIN 

1  1  hr 

1 

>) 

1 

1  day  I _ 

TABLE  is  an  optional  command  indicating  that  for  each  output  location  set  to  ’sname’  (see 
commands  POINTS,  CURVE,  FRAME,  or  GROUP,  Section  4.13.1.6,  4.13.1.3,  4.13.1.1  or 
4.13.1.2),  one  or  more  variables  should  be  written  to  a  file.  The  keywords  HEADER  and 

NOHEADER  determine  the  appearance  of  the  table.  The  filename  determines  the  destination  of  the 
data. 


'sname' 

Name  of  the  set  of  POINTS,  CURVE,  FRAME  or  GROUP  (see  Section 
4.13.1.6, 4.13.1.3, 4.13.1.1  or  4.13.1.2). 

HEADER 

Output  is  written  in  fixed  format  to  file  with  headers  giving  name  of  variable 
and  unit  per  column.  A  disadvantage  of  this  option  is  that  the  data  are  written 
in  fixed  format.  Numbers  too  large  to  be  written  will  be  shown  as  ****.  The 
number  of  header  lines  is  four. 

NOHEADER 

Output  is  written  in  floating  point  format  to  file  and  has  no  headers.  It  is 
intended  primarily  for  processing  by  other  programs.  With  some  spreadsheet 
programs,  the  HEADER  option  works  better. 

INDEXED 

A  table  on  file  is  produced  which  can  be  used  directly  (without  editing)  as  input 
to  ARCVIEW,  ARCINFO,  etc.  The  user  should  give  two  TABLE  commands, 
one  to  produce  a  file  with  XP  and  YP  as  output  quantities  and  the  other  with 

HS,  PER  or  other  output  quantities  for  processing  in  ARCVIEW  or  ARCINFO. 
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The  first  column  of  each  file  produced  by  SWAN  with  this  command  is  the 
sequence  number  of  the  output  point.  The  last  line  of  each  file  is  the  word 
END. 

’fiiarne’  Name  of  the  data  file  to  which  the  output  is  to  be  written.  Default  for  option 

HEADER  is  output  to  the  print  file  (see  Section  4.11.2.1).  In  case  of 
NOHEADER,  the  filename  is  required. 

1-1 

<  >  The  output  parameters  are  the  same  as  in  command  BLOCK. 


OUTPUT 


[tbegtbl] 


[deltbl] 

SEC 

MIN 

HR 

DAY 


The  user  requests  output  at  various  times.  If  the  user  does  not  use  this  option, 
the  program  will  give  TABLE  output  for  the  last  time  step  of  the  computation. 

Begin  time  of  output,  the  format  is: 


=  1 

ISO  notation: 

19870530.153000 

=  2 

(as  in  HP  compiler): 

'30-May-87  15:30:00’ 

=  3 

(as  in  Lahey  compiler): 

05/30/87.15:30:00 

=  4 

15:30:00 

=  5 

87/05/30  15:30:00’ 

=  6 

as  in  WAM 

8705301530 

This  format  is  installation  dependent.  See  installation  manual  on  the  SWAN 
web  site.  Default  is  ISO. 

Time  interval  of  output,  the  unit  is  indicated  in  the  next  option. 

Unit  seconds. 

Unit  minutes. 

Unit  hours. 

Unit  days. 


See  command  BLOCK  in  Section  4.13.2.2  for  details  except  when  the  x-  and  y-components  of  the 
vectorial  quantities  VEL,  FORCE  and  TRANSPORT  are  given  with  respect  to  the  problem 
coordinate  system. 

The  number  of  decimals  in  the  table  varies  for  the  output  parameters.  The  number  depends  on  the 
value  of  [hexp],  given  in  the  command  QUANTITY. 
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4.13.2.4  SPECOUT 


I  SPEC  ID  |  I  ->  ABSOLUTE  | 

SPECOUT  'sname'  <  >  <  >  ’fname’ 

1  ->  SPEC2D  |  |  RELATIVE  | 

|  ->  SEC  | 

OUTPUT  [tbegspc]  [deltspc]  <  MIN  > 

I  MR  | 

I  DAY  | 


With  the  optional  command  SPECOUT,  the  user  indicates  that  for  each  output  location  set  to 
sname  (see  Sections  4.13.1.1-3, 4.13.1.6)  the  1-D  or  2-D  variance/energy  (see  command  SET, 
Section  4.12.4.2),  density  spectrum  (either  the  relative  or  absolute  frequency  spectrum)  is  to  be 
written  to  a  data  file.  The  name  'fname'  is  required  in  this  command. 


'sname' 


SPEC2D 


SPEC  ID 


Name  of  the  set  of  POINTS,  CURVE,  FRAME  or  GROUP  (see  Sections 
4.13.1.1-3,  4.13.1.6). 

Means  that  2-D  (frequency-direction)  spectra  are  written  to  file  according  to  the 
format  described  in  Appendix  D.  The  following  data  will  be  written  to  the  file 
heading: 

•  x  and  y  (problem  coordinates)  of  the  output  point, 

•  number  of  spectral  directions  and  frequencies, 

•  spectral  directions  (Nautical  or  Cartesian  definition,  see  command  SET, 
Section  4.12.4.2)  in  degrees, 

•  spectral  frequencies  in  Hz. 

The  following  data  will  be  written  to  the  file  body: 

•  values  of  the  variance/energy  (see  command  SET,  Section  4.12.4.2)  density 
for  each  spectral  bin. 

Note:  This  output  file  can  be  used  for  defining  boundary  conditions  for 
subsequent  SWAN  runs  (command  BOUNDSPEC). 

Means  that  1-D  (frequency)  spectra  are  written  to  file  according  to  the  format 
described  in  Appendix  D. 

The  following  data  will  be  written  to  the  file  heading: 

•  x  and  y  (problem  coordinates)  of  the  output  point, 

•  number  of  spectral  frequencies, 

•  spectral  frequencies  in  Hz. 

The  following  data  will  be  written  to  the  file  body: 

•  values  of  the  variance/energy  (see  command  SET,  Section  4.12.4.2)  density 
(integrated  over  directions)  for  each  spectral  frequency, 

•  values  of  the  average  direction  for  each  spectral  frequency  (Nautical  or 
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ABS 

REL 


'fname' 

OUTPUT 


[tbegspc] 


[deltspc] 


Cartesian  definition,  see  command  SET,  Section  4.12.4.2)  in  degrees, 

•  values  of  the  directional  spreading  for  each  spectral  frequency. 

Note:  This  output  file  can  be  used  for  defining  boundary  conditions  for 
subsequent  SWAN  runs  (command  BOUNDSPEC). 

Means  that  spectra  are  computed  as  a  function  of  absolute  frequency  (i.e.  the 
frequency  as  measured  in  a  fixed  point). 

Means  that  spectra  are  computed  as  function  of  relative  frequency  (i.e.  the 
frequency  as  measured  when  moving  with  the  current). 

Name  of  the  data  file  to  which  the  output  is  written. 

The  user  requests  output  at  various  times.  If  the  user  does  not  use  this  option, 
the  program  will  give  SPECOUT  output  for  the  last  time  step  of  the 
computation. 


Begin  time  of  output,  the  format  is: 


=  1 

ISO  notation 

19870530.153000 

=  2 

(as  in  HP  compiler): 

'30-May-87  15:30:00’ 

=  3 
=  4 

(as  in  Lahey  compiler): 

05/30/87.15:30:00 

15:30:00 

=  5 

'87/05/30  15:30:00’ 

=  6 

as  in  WAM 

8705301530 

This  format  is  installation  dependent.  See  installation  manual  on  the  SWAN 
web  site.  Default  is  ISO. 


Time  interval  of  output,  the  unit  is  indicated  in  the  next  option. 


SEC  Unit  seconds. 

MIN  Unit  minutes. 


HR  Unit  hours. 


DAY  Unit  days. 


4.13.2.5  NESTOUT 


|  ->  SEC  | 

NESTOUT  'sname'  'fname'  OUTPUT  [tbegnst]  [deltnst]  <  MIN  > 

I  HR  | 

I  DAY  I 
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NESTOUT  cannot  be  used  in  ID-MODE. 

With  this  optional  command  the  user  indicates  that  the  spectra  along  a  nest  boundary  'sname’  (see 

command  NGRID,  Section  4.13.1.7)  should  be  written  to  a  data  file  with  name  'fname'.  This  name 
is  required  in  this  command. 


'sname' 


Name  of  the  set  of  output  locations  as  defined  in  command  NGRID. 


Name  of  the  data  file  to  where  the  output  is  written.  The  file  is  structured 
according  to  the  description  in  Appendix  D  and  information  about  the  boundary 
location  is  written  to  this  file.  SWAN  will  use  this  as  a  check  for  the  subsequent 
nested  run. 


OUTPUT 


[tbegnst] 


The  user  requests  output  at  various  times.  If  the  user  does  not  use  this  option,  the 
program  will  give  NESTOUT  output  for  the  last  time  step  of  the  computation. 

Begin  time  of  output,  the  format  is: 


=  1 

ISO  notation 

19870530.153000 

=  2 

(as  in  HP  compiler): 

'30-May-87  15:30:00’ 

=  3 

(as  in  Lahey  compiler): 

05/30/87.15:30:00 

=  4 

15:30:00 

=  5 

'87/05/30  15:30:00’ 

=  6 

as  in  WAM 

8705301530 

This  format  is  installation  dependent.  See  installation  manual  on  the  SWAN  web 
site.  Default  is  ISO. 


[deltnst]  Time  interval  of  output,  the  unit  is  indicated  in  the  next  option. 

SEC  Unit  seconds. 

MIN  Unit  minutes. 

HR  Unit  hours. 

DAY  Unit  days. 
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4.13.2.6  PLOTGEOGR 


I  ->  XXX 

PLOTGEOGR  'sname'  < 

|  FILE  'fname' 

I- 

(ISO  < 

U 

I- 

(VEC  < 

|... 

(CMESH)  [ipen]) 
(SUES  [ipen]) 
(LOCATION  ('sname'; 


>  'title'  <  >  & 

I  I  COORD  [marg]  | 

>  [step]  [min]  [max] )  & 

>  [scale]  [dist] )  & 

t 

& 

(LINES  [ipen])  & 

[ipen])  & 


|  ->  SEC  | 

(OUTPUT  [tbegnst]  [deltnst]  <  MIN  > 

I  HR  | 

I  DAY  I 


Option  PLOTGEOGR  cannot  be  used  in  1-D  mode. 

With  the  optional  command  PLOTGEOGR  the  user  indicates  that  a  plot  of  a  spatial  distribution  is 

required  (contour  line  plot  and/or  vector  plot).  It  is  not  possible  to  combine  two  isoline  plots  or  two 

vector  plots.  For  a  combined  contour  line/vector  plot  the  ISO  option  must  precede  the  VEC  option. 

CMESH,  SITES  and  LOCATIONS  can  be  combined  with  both  vector  and  isoline  plots. 

The  user  should  read  Section  4.7  to  be  aware  of  interpolation  errors. 

'sname'  Name  of  the  frame  (must  be  a  frame;  see  command  FRAME,  Section  4.13.1.1). 

FILE  With  this  option  the  user  can  define  a  filename  for  the  plot  file.  In  different 

PLOT. ..  commands  different  plot  files  may  be  used.  If  the  option  FILE  is  used, 
a  filename  must  be  given  for  'fname'.  If  this  option  is  not  used  then  the  program 
will  write  the  plot  data  to  the  same  plot  file  as  mentioned  in  the  last  PLOT... 
command.  If  a  filename  is  not  given  in  the  first  PLOT...  command  SWAN  will 
create  a  plot  file  with  the  name  PLF...,  where  the  run  number  as  defined  in  the 
command  PROJECT  as  'NR'  appears  on  the  dots  (only  for  PLF...). 
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'fname' 

xxx 

'title' 

COORDINATES 

[marg] 

ISO 

I-  I 

<  > 

I-  I 

[step] 

[min] 

[max] 

VEC 


Name  of  the  file  where  the  plot  output  is  to  be  written  to  (see  Section  4.12.3). 
SWAN  will  assume  a  name  for  the  plot  file. 

String  to  be  plotted  in  the  caption  of  the  plot.  It  has  a  maximum  36  character 
length.  The  project  name  and  run  number  given  in  command  PROJECT  are  also 
plotted.  If  the  user  does  not  give  ‘title’,  SWAN  will  generate  a  text  indicating 
which  quantity  and  which  frame  is  plotted.  The  maximum  length  of  the  plot 
title  is  36  characters. 

If  the  keyword  COORD  is  present  the  program  will  plot  values  of  problem 
coordinates  at  the  left  and  the  lower  side  of  the  figure.  The  coordinates  will  be 
plotted  only  if  the  x-axis  of  the  frame  indicated  by  ’sname’  is  parallel  to  the  x- 
axis  of  the  problem  coordinate  system.  If  not,  an  error  message  results. 

The  size  of  the  margin  used  to  plot  the  coordinates  (in  cm).  Default-  [marg]  = 
1.5. 

Indicates  that  a  contour  line  plot  is  requested  for  a  scalar  variable  (i.e.  not  a 
vector,  not  a  direction  (DIR  etc.)).  The  keywords  identifying  the  variable  are 
the  same  as  in  command  BLOCK. 

The  output  parameters  are  the  same  as  in  command  BLOCK.  The  scalar  and 
vector  parameters  are  separated  here  but  DIR  and  PDIR  are  considered  to  be 
scalars  in  this  context. 

The  difference  in  value  for  two  neighboring  contour  lines.  If  [step]  is  not 
specified,  SWAN  will  make  [step]  equal  to  the  difference  between  [min]  and 
[max]  divided  by  tern. 

The  minimum  value  for  which  a  contour  line  is  drawn.  If  [min]  is  not  specified 
then  SWAN  will  make  [min]  equal  to  0  if  [step]  is  specified.  If  [step]  is  not 
specified,  SWAN  will  make  a  rounded  value  near  the  smallest  value  occurring 
in  the  grid. 

The  maximum  value  for  which  a  contour  line  is  drawn.  If  [max]  is  not 
specified  then  SWAN  will  make  [max]  equal  to  10*[step]  if  [step]  is  specified, 
or  a  rounded  value  near  the  largest  value  occurring  in  the  grid  if  [step]  is  not 
specified. 

Indicates  that  a  vector  plot  is  requested  for  a  vector  or  direction  variable.  The 
keyword  identifying  the  variable  must  follow  the  keyword  VEC,  as  they  are  the 
same  as  in  BLOCK.  The  length  of  the  vectors  is  proportional  to  the  magnitude 
of  the  variable  (except  for  direction  vectors,  e.g.  DIR,  PDIR  or  TDIR).  The 
start  position  of  the  vector  is  a  grid  point  of  the  output  frame. 
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[scale] 

[dist] 

CMESH 

[ipen] 

SUES 

[ipen] 

LINES 

[ipen] 

LOCATION 

'sname' 

[ipen] 

OUTPUT 

[tbegpltg] 


Length  of  the  vectors  (in  cm  on  paper)  equal  to  the  value  of  the  vector  (in  SI 
units). 

Every  [dist]-th  vector  is  plotted  in  the  plot  (in  x-  and  y-direction),  starting  with 
the  first  vector  in  the  lower  left-hand  comer  of  the  FRAME. 

Default:  If  option  ISO  is  used  in  the  command  (i.e.  vector  and  contour  line  plot 
combined),  then  [dist]  =  5.  If  option  ISO  is  not  used  in  the  command  (i.e.  only 
a  vector  plot  is  required),  then  [dist]  =  1. 

With  this  option  the  user  indicates  that  a  plot  of  the  computational  grid  is  to  be 
plotted. 

Pen  number  to  be  used  for  the  plot  of  the  computational  grid.  If  not  given,  the 
same  pen  is  used  as  for  the  rest  of  the  picture  (usually  black). 

Names  of  towns,  regions,  etc.,  as  defined  with  the  command  SITES  are  plotted. 

Pen  number  to  be  used  for  the  display  of  the  SITES.  If  not  given,  the  same  pen 
is  used  as  for  the  rest  of  the  picture  (usually  black). 

Line(s)  as  defined  with  the  command  LINE  is/are  plotted. 

Pen  number  to  be  used  for  the  display  of  the  LINES.  If  not  given,  the  same  pen 
is  used  as  for  the  rest  of  the  picture  (usually  black). 

The  locations  of  output  point  sets  will  be  plotted  in  the  figure.  If  a  name  is 
specified  (see  below),  the  corresponding  point  set  is  displayed.  If  no  name  is 
specified,  all  point  sets  will  appear. 

Name  of  a  point  set  of  which  the  location  is  to  be  plotted  in  the  figure  (second 
occurrence  in  the  command  scheme).  If  no  'sname'  is  given,  all  output  point 
sets  will  be  displayed. 

Pen  number  to  be  used  for  the  display  of  the  LOCATIONS.  If  not  given,  the 
same  pen  is  used  as  for  the  rest  of  the  picture  (usually  black). 

The  user  requests  output  at  various  times.  If  the  user  does  not  use  this  option, 
the  program  will  give  PLOTGEOGR  output  for  the  last  time  step  of  the 
computation. 


Begin  time  of  output,  the  format  is: 


=  1 

ISO  notation 

19870530.153000 

=  2 

(as  in  HP  compiler): 

30-May-87  15:30:00' 

=  3 

(as  in  Lahey  compiler): 

05/30/87.15:30:00 

=  4 

15:30:00 
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=  5  '87/05/30  15:30:00' 

=  6  asinWAM  8705301530 

This  format  is  installation  dependent.  See  installation  manual  on  the  SWAN 

web  site.  Default  is  ISO. 

[deltpltg]  Time  interval  of  output,  the  unit  is  indicated  in  the  next  option. 

SEC  Unit  seconds. 

MIN  Unit  minutes. 

HR  Unit  hours. 

DAY  Unit  days. 


4.13.2.7  PLOTSTAR _ 

|  ->  XXX  I 

PLOTSTAR  'sname'  >  'title' 

|  FILE  'fname'  | 


( ISO  <  >  [step]  [min]  [max] ) 


(  STAR  [scale]  [dist]  [bundle] ) 

(CMESH)  [ipen]) 

(SITES  [ipen])  (LINES  [ipen]) 

(LOCATION  ('sname')  [ipen]) 


|  ->  SEC  | 

OUTPUT  [tbegnst]  [deltnst]  <  MIN  > 

I  HR  | 

I  DAY  | 


& 

& 

& 

& 


Option  PLOTSTAR  cannot  be  used  in  1-D  mode. 

This  PLOT...  command  can  be  used  to  show  the  directional  distribution  of  the  action  transport 
(integrated  over  frequency)  optionally  superimposed  on  the  scalar  variables  of  command 
PLOTGEOGR. 
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Keywords  and  numerical  input  have  the  same  meaning  as  in  the  PLOTGEOGR  command,  except 
for  the  items  mentioned  below. 


<  >  The  output  parameters  are  scalar  parameters  as  in  command  PLOTGEOGRISO. 

I- I 

STAR  Means  that  in  a  number  of  grid  points  in  the  output  frame,  lines  are  drawn  which 

have  the  direction  of  the  action  transport  associated  with  a  spectral  bundle,  and 
whose  length  is  proportional  to  the  same  action  transport.  The  action  transport  is 
defined  in  Wm. 

[scale]  Length  of  the  vectors  (in  cm  on  paper)  equal  to  the  value  of  the  vector  (in  SI 

units). 

[dist]  See  command  PLOTGEOGR,  Section  4.13.2.6. 

[bundle]  Number  of  spectral  directions  that  are  represented  by  one  arrow  in  the  plot,  i.e. 

the  arrow  shown  represents  the  average  action  transport  of  a  bundle  of  spectral 
directions,  [bundle]  is  an  integer.  It  must  be  a  divisor  of  [mdc],  the  number  of 
spectral  directions  in  the  computation.  Default:  [bundle]  =  2. 


4.13.2.8  PLOTPP 


I  ->  XXX  | 

PLOTPP  'sname'  <  >  'title' 

|  FILE  'fname'  | 


1FROUDE  | 

( PROBLEMS  <  >  [symsiz] 

|  PCONV  | 

(SITES  [ipen])  (LINES  [ipen]) 

(LOCATION  ('sname')  [ipen]) 

|  ->  SEC  | 

(OUTPUT  [tbegnst]  [deltnst]  <  MIN  > 

I  HR  I 

I  DAY  | 


& 

& 

& 

& 


Option  PLOTPP  cannot  be  used  in  1-D  mode. 
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SWAN  will  report  that  numerical  problems  have  occurred,  should  they  arise  during  the 
computation.  This  optional  command  shows  the  locations  of  the  problem  points  by  indicating  that  a 
plot  of  problem  points  is  required.  The  points  will  be  shown  in  the  plot  with  a  symbol  specific  to 
the  nature  of  the  problem.  SITES  and  LOCATIONS  can  be  combined  with  plots  of  problem  points. 
It  is  not  possible  to  combine  this  plot  with  isoline  or  vector  plots. 

Keywords  and  numerical  input  have  the  same  meaning  as  in  the  PLOTGEOGR  command,  except 
for  the  items  mentioned  below. 


FROUDE 


PCONV 


If  the  current  velocity  is  relatively  large,  with  a  Froude  number  larger  than  0.8, 
it  will  be  reduced  such  that  the  Froude  number  becomes  equal  to  0.8.  (see 
command  READINP  CURRENT,  Section  4.12.7.2). 

If  the  linear  equation  solver,  used  in  the  case  of  currents,  does  not  converge  in  a 
grid  point,  the  computation  is  not  terminated  and  a  warning  is  printed. 


If  none  of  the  above  alternatives  is  mentioned,  both  types  of  problem  points  will  be  shown. 


[symsiz]  The  size  of  the  symbols  as  they  appear  in  the  plot,  in  cm.  Default:  [symsiz]  = 

0.18  (cm). 


4.13.2.9  PLOTSPEC 


PLOTS  PEC  'sname' 


|  ->  XXX 


< 


>  'title' 


FILE  'fname' 


|  ->  NORMALIZED  | 
SPECTRUM  <  > 

|  NONORMALIZED| 


(FREQ  < 


->  [fmax]  [fmid] 


( <  [ch]  > ) 
|->  ABS  | 


>  < 


|  NORMALIZED 


(OUTPUT  [tbegplts]  [deltplts]) 


» 


REL 


|  ->  SEC  | 

<  MIN  > 

I  HR  I 
I  DAY  I 


& 


& 


& 


With  this  optional  command  the  user  instructs  SWAN  to  produce  a  polar  plot  of  the  2-D  spectrum 
at  POINTS  or  along  a  CURVE  (see  Section  4.13.1.6  or  4.13.1.3). 
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'sname' 

FILE 

'fname' 

xxx 

'title' 

SPECTRUM 

NORMALIZED 

NONORMALIZED 

[ch] 

FREQUENCY 

[fmax] 

[fmid] 


Name  of  the  points  or  curve  (see  Section  4.13.1.6  or  4.13.1.3), 

See  command  PLOTGEOGR,  Section  4.13.2.6. 

Name  of  the  file  where  the  plot  output  is  written  to  (see  Section  4.12.3), 
SWAN  will  assume  a  name  for  the  plot  file. 

String  to  be  plotted  in  the  caption  of  the  plot,  maximum  36  characters  long. 
The  project  name  and  the  run  number  given  in  the  command  PROJECT  are 
plotted.  The  maximum  length  of  the  plot  title  is  36  characters.  Default:  title 

_  t  » 


Indicates  that  a  polar  plot  of  the  spectrum  is  requested. 

The  variance/energy  densities  (see  command  SET,  Section  4.12.4.2)  in  the 
2-D  plot  will  be  normalized,  i.e.  the  ratio  of  the  variance/energy  density  and 
the  peak  variance/energy  density  is  plotted;  consequently  the  values  of  [ch] 
(see  below)  must  be  smaller  than  one.  Note  that  the  1-D  spectrum  is 
always  normalized. 

The  variance/energy  densities  (see  command  SET,  Section  4.12.4.2)  in  the 
2-D  plot  will  not  be  normalized.  Note  that  the  1-D  spectrum  is  always 
normalized. 

Contour  levels  for  the  variance/energy  (see  command  SET,  Section 
4.12.4.2)  density.  In  contrast  with  the  plot  as  described  in  the  commands 
PLOTSTAR  ISO  and  PLOTGEOGR  ISO  the  contour  levels  are  not 
equidistant.  Because  of  the  large  variation  in  values  of  variance/energy 
densities  (see  command  SET,  Section  4.12.4.2)  one  is  advised  to  distribute 
the  levels  in  a  logarithmic  manner,  e.g.,  0.01, 0.03,  0.1,  0.3,  1.,  3.,  10.  (in  m 
2  /Hz/Rad). 

Note:  If  no  values  are  given  for  [ch]  the  program  will  use  0.02,  0.1  and  0.5 
(it  is  assumed  that  these  are  normalized  values). 

The  part  after  this  keyword  serves  to  define  the  frequency  scale  of  the 
figure. 

The  maximum  frequency  for  which  the  variance/energy  density  (see 
command  SET,  Section  4.12.4.2)  is  plotted.  Default  [fmax]  =  0.5*[fhigh] 
(see  command  CGRID,  Section  4.12.6.1).  SWAN  will  plot  a  dashed  circle 
for  this  frequency.  Note:  The  program  will  also  plot  a  circle  for  the 
frequency  [flow]  (see  command  CGRID,  Section  4.12.6.1). 

An  additional  circle  will  be  plotted  at  frequency  [fmid],  [fmid]  must  be 


101 


SWAN  User’s  Manual 


less  than  [fmax],  Default:  no  circle. 


NORMALIZED 


ABSOLUTE 


RELATIVE 


OUTPUT 


[tbegplts] 


[deltplts] 

SEC 

MIN 

HR 

DAY 


The  frequency  scale  is  normalized  with  the  peak  frequency.  If  this  keyword 
does  not  appear,  non-normalized  values  for  the  frequency  are  assumed. 

The  spectral  density  is  defined  along  the  absolute  frequency  axis,  i.e.,  the 
frequency  as  measured  in  a  geographically  fixed  location.  This  is  the 
default  option. 

The  spectral  density  is  defined  along  the  relative  frequency  axis,  i.e.,  the 
frequency  as  measured  in  a  point  moving  with  the  current. 

The  user  requests  output  at  various  times.  If  the  user  does  not  use  this 
option,  the  program  will  give  PLOTSPEC  output  for  the  last  time  step  of 
the  computation. 

Begin  time  of  output,  the  format  is: 


=  1 

ISO  notation 

19870530.153000 

=  2 

(as  in  HP  compiler): 

'30-May-87  15:30:00’ 

=  3 

(as  in  Lahey  compiler): 

05/30/87.15:30:00 

=  4 

15:30:00 

=  5 

87/05/30  15:30:00’ 

=  6 

as  in  WAM 

8705301530 

This  format  is  installation  dependent.  See  installation  manual  on  the 
SWAN  web  site.  Default  is  ISO. 

Time  interval  of  output,  the  unit  is  indicated  in  the  next  option. 

Unit  seconds. 

Unit  minutes. 

Unit  hours. 

Unit  days. 


4. 13.3  Compute,  Hotfile  and  Stop 

4.13.3.1  COMPUTE 


COMPUTE  ( < 


STATIONARY  [time] 


->  SEC 
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|  ->  NONSTAT  Ttbegcl  fdeltcl  <  MIN  >  [tendc]  | 

I  HR  | 

I  DAY  | 


COMPUTE  orders  SWAN  to  start  the  computation(s). 

If  the  SWAN  mode  is  stationary  (see  command  MODE,  Section  4.12.4.3),  then  the  only  command 
given  is  COMPUTE.  If  the  SWAN  mode  is  nonstationary  (see  command  MODE,  Section 
4.12.4.3),  then  the  computation  can  be  either  stationary  (at  the  specified  time:  option 
STATIONARY)  or  nonstationary  (over  the  specified  period  of  time:  [tbegc],  etc.). 

To  verify  input  to  SWAN  such  as  water  depth  and  wind  fields,  SWAN  can  be  run  without 
computations  (zero  iterations  by  using  command  NUM  ACCUR  itermx  =  0). 

In  the  case  MODE  NONSTATIONARY,  several  COMPUTE  commands  may  appear,  where  the 
wave  state  at  the  end  of  one  computation  is  used  as  initial  state  for  the  next  one,  unless  a  command 
INIT  appears  in  between  the  two  COMPUTE  commands.  This  enables  the  user  to  make  a 
stationary  computation  to  obtain  the  initial  state  for  a  nonstationary  computation  and/or  to  change  a 
boundary  condition,  the  computational  time  step  during  a  computation,  etc. 

STATIONARY  A  stationary  computation  is  to  be  made. 

[time]  Time  level  for  which  the  stationary  run  is  to  be  made,  the  format  is: 


=  1 

ISO  notation 

19870530.153000 

=  2 

(as  in  HP  compiler): 

"30-May-87  15:30:00’ 

=  3 
=  4 
=  5 

(as  in  Lahey  compiler): 

05/30/87.15:30:00 

15:30:00 

'87/05/30  15:30:00’ 

=  6 

as  in  WAM 

8705301530 

This  format  is  installation  dependent.  See  installation  manual  on  the 
SWAN  web  site.  Default  is  ISO. 

NONSTATIONARY  A  nonstationary  computation  is  to  be  made. 

[tbegc]  The  start  date  and  time  of  the  nonstationary  computation.  For  format,  see 

[time].  Default:  The  time  read  from  a  hotfile  (see  command  INIT 
HOTSTART,  Section  4.12.8.7),  the  end  time  [tendc]  of  the  previous 
nonstationary  computation  or  the  [time]  of  the  previous  stationary 
computation  in  the  same  SWAN  run  (if  any). 

[deltc]  The  time  step  of  the  nonstationary  computation.  The  unit  is  indicated  in  the 

following  options. 

SEC  Unit  seconds. 


103 


SWAN  User’s  Manual 


MIN  Unit  minutes. 

HR  Unit  hours. 

DAY  Unit  days. 

ttendcl  The  end  time  of  the  nonstationary  computation.  For  format,  see  [time]. 


4.13.3.2  HQTFILE 
HOTFILE  'fname' 


This  command  can  be  used  to  write  the  entire  wave  field  at  the  end  of  a  computation  to  an 
initialization  file,  e.g.  to  be  used  as  initial  condition  in  a  subsequent  SWAN  run  (see  command 
INITIAL  HOTSTART,  Section  4.12.8.7),  This  command  must  be  entered  immediately  after  a 
COMPUTE  command. 


The  format  of  the  initialization  file  is  identical  to  the  format  of  the  files  written  by  SPECOUT 
(option  SPEC2D). 

'fname'  Name  of  the  file  to  which  the  wave  field  is  written. 


4.13.3.3  STOP 
STOP 


This  required  command  marks  the  end  of  the  commands  in  the  command  file. 

Note:  The  command  STOP  must  always  be  the  last  command  in  the  input  file;  any  information  in 
the  input  file  beyond  this  command  is  ignored. 
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4.14  Definitions  of  Variables 

In  SW  AN  a  number  of  variables  mostly  related  to  waves  are  used  as  input  and  output.  The 
definitions  of  these  variables  are  mostly  conventional. 

HSIGN  Significant  wave  height  (Hs  in  m),  defined  as: 

H s  =  4J  f  [£(©,0)r/cod9  ,  where  E( to,  0)  is  the  variance  density  spectrum. 


HSWELL  Significant  wave  height  (Hswe//  in  m),  associated  with  the  low  frequency  part  of  the 
spectrum,  defined  as: 

swell  2# 

J  Jffco,  9)d(dd9  ,  where  E((o,  0)  is  the  variance  density  spectrum, 

0  0 

and  GW//  =  ^11 .  fsweii  is  0.1  Hz  by  default.  It  can  be  changed  in  the  command 

QUANTITY. 


TM01 


TM02 


DIR 


Mean  absolute  wave  period  (in  s)  of  E(oi,  0),  defined  as: 


TmOl  ~ 


^(nE(<y,9)dod9 

^E{(T,9)dad9 


mm .  ( 

-  rBi 


J .  V 


jjio£(co,  9)d(od9  S 

M 


-i 


VJ 


where  G)  is  the  absolute  radian  frequency,  determined  by  the  Doppler  shifted 
dispersion  relation. 


Mean  absolute  wave  period  (in  s)  of  £(co,  0),  defined  as 
'  |Jo)2£((o,0)^(od0 


f 


=  2  7l\ 


(  ff (o2E((7,9)d(7d9S]}/2 


<T,9)dcFd9  ^ 


where  G)  is  the  absolute  radian  frequency,  determined  by  the  Doppler  shifted 
dispersion  relation. 


Mean  wave  direction  (in  degrees,  Cartesian  or  Nautical  convention),  as 
conventionally  defined  (Kuik  et  al.,  1988). 

[DIR]  =  arctan  [ Jsin(0)£(<T, 9)d<j d9/  jcos(0)£(<7,0)dcr  JgJ 

DIR  is  the  direction  normal  to  the  wave  crests.  If  currents  are  present,  DIR  is 
different  from  the  direction  of  the  energy  transport  TDIR. 
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Peak  direction  of  £(0)  =  jE(to,0)<fo>  =  \E{<j,$)dt 7  (in  degrees,  Cartesian  or 
Nautical  convention). 


TDIR 

RTM01 


RTP 


Direction  of  energy  transport  (in  degrees,  Cartesian  or  Nautical  convention). 

Mean  relative  wave  period  (in  s)  of  E(o,  0),  defined  as: 

RTmW  =2 n{^oE(a$)d(rdQI  \\E{(T,Q)d<7dQy 
Equal  to  TM01  in  the  absence  of  currents. 

Relative  peak  period  (in  s)  of  E(a)  (equal  to  absolute  peak  period  in  the  absence  of 
currents). 


PER  Average  absolute  period  (in  s)  defined  as: 

Tm,P-vP  =2x\«>p-]E((j,e)d(TdQ/  j(opE(cr,Q)d(rdQ 

The  power  p  can  be  chosen  by  using  QUANTITY.  If  p  =  1  (the  default  value  in 
QUANTITY)  PER  and  RPER  are  identical  to  TM01  and  RTM01,  respectively.  If  p 
=  0,  the  average  period  is  obtained  as  used  in  WAM,  i.e.  T(m,-1,0). 

RPER  Average  relative  period  (in  s)  defined  as: 

Tm  =27rjcrp~'E((7,e)do-dO/  jcrp E(a,Q)d<jdd 

The  power  p  can  be  chosen  by  using  QUANTITY.  If  p  =  1  (the  default  value  in 
QUANTITY),  PER  and  RPER  are  identical  to  TM01  and  RTM01,  respectively.  If 
P  =  0,  the  average  period  is  obtained  as  used  in  WAM,  i.e.  Tm(-1,0). 

FSPR  The  normalized  frequency  width  of  the  spectrum  (frequency  spreading),  as  defined 

by  Battjes  and  van  Vledder  (1984): 


FSPR  = 


\E((a)eia>Tdu 


IE.. 


for  x  —  Tmo2 


The  one-sided  directional  width  of  the  spectrum  (directional  spreading  or 
directional  standard  deviation,  in  degrees),  defined  as: 

DSPRl  =(ir)  l<2sin^0~®)/2)}2D(0)^e’ 

computed  conventionally  for  pitch-and-roll  buoy  data  (Kuik  et  al„  1988). 
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[MS] 


DISSIP 

WLEN 


This  is  the  standard  definition  for  WAVEC  buoys  integrated  over  all  frequencies: 

(  r  .  .  -i>0 


K 


(DSPR - Y  =2 

180  1 


1- 


(  jsin(0) 


|E((T,0)Jct 

\E(G)d(7 


r/0)2+(Jcos(0) 


|E(<t,0)J<t 

\E(<7)d(J 


dQ)2 


SWAN  input  in  the  commands  BOUNDPAR  and  BOUNDSPEC  defined  as  the 
directional  distribution  of  incident  wave  energy,  D(0)  =  A  [cos(0)]**[MS],  at  all 
frequencies.  [MS]  is  not  necessarily  an  integer  but  is,  for  this  directional 
distribution,  related  to  the  one-sided  directional  spread  of  the  waves  (DSPR)  as 
follows: 


[MS]  DSPR  (°) 


1. 

37.5 

2. 

31.5 

3. 

27.6 

4. 

24.9 

5. 

22.9 

6. 

21.2 

7. 

19.9 

8. 

18.8 

9. 

17.9 

10. 

17.1 

15. 

14.2 

20. 

12.4 

30. 

10.2 

40. 

8.9 

50. 

8.0 

60. 

7.3 

70. 

6.8 

80. 

6.4 

90. 

6.0 

100. 

5.7 

200. 

4.0 

400. 

2.9 

800. 

2.0 

Energy  dissipation  per  unit  time  due  to  the  sum  of  bottom  friction,  whitecapping 
and  depth  induced  wave  breaking  (in  W/m2  of  m2/s,  depending  on  command  SET). 


The  mean  wavelength. 
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STEEPNESS 

Qb 

TRANSP 

VEL 

WIND 

FORCE 


URMS 


WLEN  =  2k 


jkpE((j,Q)dadQ  " 
jkp~'E(a,Q)dadQ^ 


-I 


see  command  QUANTITY,  Section  4.13.2.1  (where  p  =  1  is  default). 


Wave  steepness,  computed  as: 
STEEPNESS  =  HSIGN  /  WLEN 


Fraction  of  breakers  in  expression  of  Battjes  and  Janssen  (1978),  see  Section  5.1. 

Energy  transport  with  components  Px  =  ^pgcxE{(j,%)d<rd%  and 

—  jjp8cyE(0'tQ)d(TdB ,  where  x  and  y  relate  to  the  problem  coordinate  system. 

The  exception  is  output  with  BLOCK  in  combination  with  FRAME,  where  x  and  y 
relate  to  the  x-axis  and  y-axis  of  the  output  frame. 


Current  velocity  with  components  in  x-  and  y-direction  of  the  problem  coordinate 
system.  The  exception  is  output  with  BLOCK  in  combination  with  FRAME,  where 
x  and  y  relate  to  the  x-axis  and  y-axis  of  the  output  frame. 

Wind  velocity  with  components  in  x-  and  y-direction  of  the  problem  coordinate 
system.  The  exception  is  output  with  BLOCK  in  combination  with  FRAME,  where 
x  and  y  relate  to  the  x-axis  and  y-axis  of  the  output  frame. 


Wave  induced  force  per  unit  surface  area  (gradient  of  the  radiation  stresses)  where 
x  and  y  relate  to  the  problem  coordinate  system.  The  exception  is  output  with 
BLOCK  in  combination  with  FRAME,  where  x  and  y  relate  to  the  x-axis  and  y-axis 
of  the  output  frame. 


*3. 
dy  ’ 


and 


ay  ’ 


where  S  is  the  radiation  stress  tensor: 
Sxx  =  PS  J[«cos2  0  +  n  -  Y2\Eda dQ 
S„  =  Syx  =  pg  J/isin  GcosG Edo  dQ 
Syy  =  pg  Jf «  sin 2  0  +  n  -  fyEde dQ 


and  n  is  the  ratio  of  group  velocity  over  phase  velocity. 


Root-mean-square  value  of  the  orbital  motion  near  the  bottom  Unns  =  <{U2)>m 
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UBOT 


Root-mean-square  value  of  the  maxima  of  the  orbital  motion  near  the  bottom. 


uh.=4iu 


rms  * 


LEAK  Numerical  loss  of  energy  equal  to  cqE(g),  0)  across  boundaries  0i  =  [dirl]  and 

02  =  [dir2]  of  a  directional  sector  (see  command  CGRID,  Section  4.12.6.1). 

TIME  Full  date-time  string. 

TSEC  Time  in  seconds  with  respect  to  a  reference  time  (see  command  QUANTITY, 

Section  4.13.2.1). 

SETUP  The  elevation  of  mean  water  level  (relative  to  still  water  level)  induced  by  the 

radiation  stress  gradient  of  the  waves. 

Cartesian  Direction  convention:  The  direction  is  the  angle  between  the  vector  and  the  positive 
x-axis,  measured  counter-clockwise  (the  direction  to  where  the  waves  are  going  or 
to  where  the  wind  is  blowing). 

Nautical  Direction  convention:  The  direction  +  180°  of  the  vector  from  geographic  North 

measured  clockwise  (the  direction  from  where  the  waves  are  coming  or  from  where 
the  wind  is  blowing). 


5.0  Functional  Description 

5.1  Model  Formulation 

5.1.1  General  Formulation 

The  waves  in  SWAN  are  described  with  the  two-dimensional  wave  action  density  spectrum,  even 
when  nonlinear  phenomena  dominates,  such  as  in  the  surf  zone.  The  rationale  for  using  the 
spectrum  in  such  highly  nonlinear  conditions  is  that  even  in  such  conditions  it  seems  possible  to 
predict  with  reasonable  accuracy  spectral  distribution  of  the  second  order  moment  of  the  waves 
(although  it  may  not  be  sufficient  to  fully  describe  the  waves  statistically).  The  action  density 
spectrum  rather  than  the  energy  density  spectrum  is  considered  in  SWAN,  since  in  the  presence  of 
currents,  action  density  is  conserved  whereas  energy  density  is  not  (e.g.,  Whitham,  1974).  The 
independent  variables  are  the  relative  frequency  (as  observed  in  a  frame  of  reference  moving  with 
the  action  propagation  velocity)  and  the  wave  direction,  which  is  normal  to  the  wave  crest  of  each 
spectra]  component.  The  action  density  is  equal  to  the  energy  density  divided  by  the  relative 
frequency.  In  SWAN,  this  spectrum  may  vary  in  time  and  space. 
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5.1.1. 1  Action  Balance  Equation 


The  evolution  of  the  wave  spectrum  in  SWAN  is  described  by  the  spectral  action  balance  equation, 
which  for  Cartesian  coordinates  is  (e.g.,  Hasselmann  et  al.,  1973)  defined  by: 


—  ^  +  —CXN  +  4~c  N  +-^-caN  +  ^-c0N  =  — 

dt  dx  dy  3<J  30  o 


(la) 


The  first  term  in  the  left-hand  side  of  this  equation  represents  the  local  rate  of  change  of  action 
density  in  time.  The  second  and  third  term  represent  propagation  of  action  in  geographical  space, 
with  propagation  velocities  cx  and  cy  in  x-  and  y-space,  respectively.  The  fourth  term  represents 
shifting  of  the  relative  frequency  due  to  variations  in  depths  and  currents,  with  propagation  velocity 
Cain  (7-space.  The  fifth  term  represents  depth-induced  and  current-induced  refraction  with 
propagation  velocity  ce  in  6  -space.  The  expressions  for  these  propagation  speeds  are  taken  from 
linear  wave  theory  (as  seen  in  Whitham,  1974;  Mei,  1983;  Dingemans,  1997).  The  term  S  (= 
S(cr,0))  at  the  right  hand  side  of  the  action  balance  equation  is  the  source  term  in  terms  of  energy 
density  representing  the  effects  of  generation,  dissipation  and  nonlinear  wave-wave  interactions.  A 
brief  summary  of  the  formulations  that  are  used  for  the  various  source  terms  in  SWAN  is  given 
next.  More  details  are  given  in  Section  5.1.3, 

In  view  of  the  use  of  SWAN  at  shelf  sea  or  oceanic  scale  the  user  can  choose  to  express  the  basic 
equation  in  spherical  coordinates: 

iN+ic^+(cosf,r'^c'cos^+£^/v+ic^^  ■  m 

with  longitude,  A  and  latitude,  (p . 


5.1.1.2  Wind  Input 

Transfer  of  wind  energy  to  waves  is  described  in  SWAN  with  a  resonance  mechanism  (Phillips, 
1957)  and  a  feedback  mechanism  (Miles,  1957).  The  corresponding  source  term  for  these 
mechanisms  is  commonly  described  as  the  sum  of  linear  and  exponential  growth: 

Sm(<T’0)  =  A  +  BE(cr,Q),  (2) 

in  which  A  describes  linear  growth  and  BE  exponential  growth.  A  and  B  depend  on  wave  frequency 
and  direction,  and  wind  speed  and  direction.  The  effects  of  currents  are  accounted  for  by  using  the 
apparent  local  wind  speed  and  direction.  The  expression  for  the  term  A  is  due  to  Cavaleri  and 
Malanotte-Rizzoli  (1981),  with  a  filter  to  avoid  growth  at  frequencies  lower  than  the  Pierson- 
Moskowitz  frequency  (Tolman,  1992a).  Two  optional  expressions  for  the  coefficient  B  are  used  in 
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the  model.  The  first  is  taken  from  an  early  version  of  the  WAM  model  (known  as  WAM  Cycle  3, 
the  WAMDI  group,  1988).  It  is  due  to  Snyder  et  al.  (1981),  rescaled  in  terms  of  friction  velocity  U 
by  Komen  et  al.  (1984).  The  drag  coefficient  to  relate  U  to  the  driving  wind  speed  at  10  m 
elevation  U\o  is  taken  from  Wu  (1982).  The  second  expression  for  B  in  SWAN  is  taken  from  the 
most  recent  version  of  the  WAM  model  (known  as  WAM  Cycle  4,  Komen  et  al.,  1994).  It  is  due  to 
Janssen  (1991a),  and  it  accounts  explicitly  for  the  interaction  between  the  wind  and  the  waves  by 
considering  atmospheric  boundary  layer  effects  and  the  roughness  length  of  the  sea  surface.  The 
corresponding  set  of  equations  is  solved  (as  in  the  WAM  model)  with  the  iterative  procedure  of 
Mastenbroek  et  al.  (1993). 

5.1.1.3  Dissipation 

The  dissipation  term  of  wave  energy  is  represented  by  the  summation  of  three  different 
contributions:  whitecapping,  Sds,w(<J,  0),  bottom  friction,  Sds,b(o,  0),  and  depth-induced  breaking, 

Sds.bti^  0)- 

Whitecapping  is  primarily  controlled  by  the  steepness  of  the  waves.  In  presently  operating  third- 
generation  wave  models  (including  SWAN)  the  whitecapping  formulations  are  based  on  a  pulse- 
based  model  (Hasselmann,  1974),  as  adapted  by  the  WAMDI  group  (1988): 

■s*,w(<T>e)  =  -r^i£(°'’e)’  (3) 

k 

where  T  is  a  steepness  dependent  coefficient,  k  is  wave  number,  and  d  and  k  denote  a  mean 
frequency  and  a  mean  wave  number,  respectively  (cf.  the  WAMDI  group,  1988).  Komen  et  al. 
(1984)  estimated  the  value  of  T  by  closing  the  energy  balance  of  the  waves  in  fully  developed 
conditions.  This  implies  that  the  T  value  depends  on  the  wind  input  formulation  used.  Since  two 
expressions  are  used  for  SWAN  wind  input,  two  values  for  T  are  also  used.  The  first  is  due  to 
Komen  et  al.  (1984,  as  in  Cycle  3  of  the  WAM  model)  and  is  used  when  the  wind  input  coefficient 
B  (Komen  et  al.,  1984)  is  used.  The  second  expression  is  an  adaptation  based  on  Janssen  (1991a;  as 
in  Cycle  4  of  the  WAM  model;  see  Janssen,  1991b;  Gunther  et  al.,  1992)  and  used  when  the  wind 
input  term  B  of  Janssen  (1991a)  is  used.  Young  and  Banner  (1992)  and  Banner  and  Young  (1994) 
have  shown  that  the  results  of  closing  the  energy  balance  in  this  manner  depend  critically  on  the 
choice  of  a  high-frequency  cut-off  frequency  above  which  a  diagnostic  spectral  tail  is  used.  In 
SWAN,  this  cut-off  frequency  is  different  that  used  in  WAM.  Differences  in  the  growth  rates 
between  WAM  and  SWAN  are  therefore  to  be  expected. 

Depth-induced  dissipation  may  be  caused  by  bottom  friction,  bottom  motion,  percolation,  or 
backscattering  on  bottom  irregularities  (Shemdin  et  al.,  1978).  For  continental  shelf  seas  with 
sandy  bottoms,  the  dominant  mechanism  appears  to  be  bottom  friction  (Bertotti  and  Cavaleri,  1994) 
which  can  be  represented  as: 


g2  sinh2(fai) 


E{ct,Q), 


(4) 
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in  which  Cbottom  is  a  bottom  friction  coefficient  that  generally  depends  on  the  bottom  orbital  motion 
represented  by  (/mis-  Many  models  have  been  proposed  since  the  pioneering  paper  of  Putnam  and 
Johnson  (1949).  Hasselmann  et  al.  (JONSWAP,  1973)  suggested  using  an  empirically  obtained 
constant  that  seems  to  perform  well  in  a  variety  of  conditions  as  long  as  a  suitable  value  is  chosen 
(typically  different  for  swell  and  wind  sea;  Bouws  and  Komen,  1983).  A  nonlinear  formulation 
based  on  drag  was  proposed  by  Hasselmann  and  Collins  (1968)  and  simplified  by  Collins  (1972). 
More  complicated,  eddy  viscosity  models  have  been  developed  by  Madsen  et  al.  (1988)  and  by 
Weber  (1989,  1991a,  1991b).  Considering  the  large  bottom  condition  variations  in  coastal  areas 
(bottom  material,  bottom  roughness  length,  ripple  height  etc.),  there  is  no  field  data  evidence  to 
give  preference  to  a  particular  friction  model  (Luo  and  Monbaliu,  1994).  For  this  reason,  the 
simplest  of  each  of  these  friction  models  has  been  implemented  in  SWAN:  the  empirical 
JONSWAP  model  of  Hasselmann  et  al.  (1973),  the  drag  law  model  of  Collins  (1972),  and  the  eddy- 
viscosity  model  of  Madsen  et  al.  (1988).  The  effect  of  a  mean  current  on  the  wave  energy 
dissipation  due  to  bottom  friction  is  not  taken  into  account  in  SWAN.  The  reasons  for  this  are 
given  by  Tolman  (1992b),  who  argues  that  state-of-the-art  expressions  vary  too  widely  in  their 
effects  to  be  acceptable.  He  found  that  the  error  in  computing  a  correct  estimate  of  the  bottom 
roughness  length  scale  has  a  much  larger  impact  on  the  energy  dissipation  rate  than  the  effect  of  a 
mean  current. 

The  process  of  depth-induced  wave  breaking  is  still  poorly  understood  and  little  is  known  about  its 
spectral  modeling.  In  contrast  to  this,  the  total  dissipation  (i.e.,  integrated  over  the  spectrum)  due  to 
this  type  of  wave  breaking  can  be  well  modeled  with  the  dissipation  of  a  bore  applied  to  the 
breaking  waves  in  a  random  field  (Battjes  and  Janssen,  1978;  Thornton  and  Guza,  1983). 

Laboratory  observations  (e.g.,  Battjes  and  Beji,  1992;  Vincent  et  al.  1994;  Arcilla  et  al.,  1994  and 
Eldeberky  and  Battjes,  1996)  show  that  the  shape  of  initially  uni-modal  spectra  propagating  across 
simple  (barred)  beach  profiles  is  insensitive  to  depth-induced  breaking.  This  has  led  Eldeberky  and 
Battjes  (1995)  to  formulate  a  spectral  version  of  the  bore  model  of  Battjes  and  Janssen  (1978)  that 
conserves  the  spectral  shape.  Expanding  their  expression  to  include  directions,  the  expression  used 
in  SWAN  is: 


SdsJ,M,Q)  =  ^E{a,Q),  (5) 

in  which  Etot  is  the  total  wave  energy  and  D,0/(which  is  negative)  is  the  rate  of  dissipation  of  the 
total  energy  due  to  wave  breaking.  (Battjes  and  Janssen,  1978).  Adding  a  quadratic  dependency  on 
frequency,  as  suggested  by  Mase  and  Kirby  (1992),  seems  to  have  no  noticeable  effect  on  SWAN 
results.  Chen  and  Guza  (1997)  inferred  (from  observations  and  simulations  with  a  Boussinesq 
model)  that  the  high-frequency  levels  are  insensitive  to  such  frequency  dependency  because 
increased  nonlinear  energy  transfer  compensates  an  increased  dissipation  at  high  frequencies; 
however,  they  did  find  the  frequency  dependency  to  be  relevant  in  time  domain.  The  value  of  Dto, 
depends  critically  on  the  breaking  parameter  y  =  HmaJd,  in  which  //^  is  the  maximum  possible 
individual  wave  height  in  the  local  water  depth.  In  SWAN,  a  constant  value  and  a  variable  value  are 
available.  The  constant  value  is  y  =  0.73  (the  mean  value  of  the  data  set  of  Battjes  and  Stive,  1985). 
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SWAN  can  estimate  wave  transmission  through  a  (line-)  structure  such  as  a  breakwater  or  dam. 
Such  an  obstacle  will  affect  the  wave  field  in  two  ways,  first  by  reducing  the  wave  height  locally  all 
along  its  length,  and  second  by  causing  diffraction  around  its  end(s).  The  model  is  not  able  to 
account  for  diffraction.  In  irregular,  short-crested  wave  fields,  however,  it  seems  that  the  effect  of 
diffraction  is  small,  except  in  a  region  less  than  one  or  two  wavelengths  away  from  the  tip  of  the 
obstacle  (Booij  et  al.,  1993).  Therefore,  the  model  can  reasonably  account  for  waves  around  an 
obstacle  if  the  directional  spectrum  of  incoming  waves  is  not  too  narrow.  Since  obstacles  usually 
have  a  transversal  area  that  is  too  small  to  be  resolved  by  the  bottom  grid  in  SWAN,  an  obstacle  is 
modeled  as  a  line.  If  the  crest  of  the  breakwater  is  at  a  level  where  at  least  a  portion  of  the  waves 
can  pass  over,  the  transmission  coefficient  Kt  is  a  function  of  wave  height  and  the  difference  in  crest 
level  and  water  level.  Kt  is  defined  as  the  ratio  of  the  significant  wave  height  at  the  downwave  side 
of  the  dam  over  the  (significant)  wave  height  at  the  upwave  side  (Goda  et  al.,  1967): 


K,  =  0.5 


1-sin 


K 


2a 


W 


V#. 


+p 


JJ 


for  -B-a< — <a-B, 

H: 


(6) 


where  F  =  h-d  is  the  freeboard  of  the  dam.  Hi  is  the  incident  significant  wave  height  at  the  upwave 
side  of  the  obstacle  (dam),  h  is  the  crest  level  of  the  dam  above  the  reference  level,  d  is  the  mean 
water  level  relative  to  the  reference  level,  and  the  coefficients  a,  p  depend  on  the  shape  of  the  dam. 
Table  5.1-1  provides  a  summary  of  the  a,  coefficients  and  the  cases  in  which  they  are  used. 


Table  5.1-1.  Coefficients  a,  /?  determined  by  the  shape  of  the  dam  (Seelig,  1979). 


Case 

a 

P _ 

vertical  thin  wall 

1.8 

0.1 

caisson 

2.2 

0.4 

dam  with  slope  1:3/2 

2.6 

0.15 

The  above  expression  is  based  on  experiments  in  a  wave  flume,  so  it  is  only  valid  for  normal 
incidence  waves.  No  data  are  available  on  oblique  waves  so  it  is  assumed  that  the  transmission 
coefficient  does  not  depend  on  direction.  A  change  in  wave  frequency  may  also  be  expected  since 
the  process  above  the  dam  is  often  highly  nonlinear.  Again,  there  is  little  information  available,  so 
it  is  assumed  that  the  frequencies  remain  unchanged  over  an  obstacle.  Only  the  energy  scale  of  the 
spectrum  is  affected,  not  the  spectral  shape. 


5.1.1.4  Nonlinear  Wave-wave  Interactions 

In  deep  water,  quadruplet  wave-wave  interactions  dominate  the  evolution  of  the  spectrum.  They 
transfer  wave  energy  from  the  spectral  peak  to  lower  frequencies,  thus  moving  the  peak  frequency 
to  lower  values  and  to  higher  frequencies  where  the  energy  is  dissipated  by  whitecapping.  In  very 
shallow  water,  triad  wave-wave  interactions  transfer  energy  from  lower  frequencies  to  higher 
frequencies,  resulting  in  higher  harmonics  (Beji  and  Battjes,  1993).  Low-frequency  energy 
generation  by  triad  wave-wave  interactions  is  not  considered  here. 
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A  full  computation  of  the  quadruplet  wave-wave  interactions  is  extremely  time  consuming  and  not 
convenient  for  any  operational  wave  model.  A  number  of  techniques  based  on  parametric  methods 
or  other  approximations  have  been  proposed  to  improve  computational  speed  (see  Young  and  Van 
Vledder,  1993  for  a  review).  SWAN’s  computations  are  carried  out  with  the  Discrete  Interaction 
Approximation  (DIA)  of  Hasselmann  et  al.  (1985).  DLA  has  been  deemed  quite  successful  in 
describing  the  essential  features  of  a  developing  wave  spectrum  (Komen  et  al.,  1994),  but  for  uni¬ 
directional  waves,  the  approximation  is  not  valid.  In  fact,  the  quadruplet  interaction  coefficient  for 
these  waves  is  nearly  zero  (G.Ph.  van  Vledder,  personal  communication,  1996).  For  finite-depth 
applications,  Hasselmann  and  Hasselmann  (1981)  have  shown  that  for  a  JONSWAP-type  spectrum 
the  quadruplet  wave-wave  interactions  may  be  scaled  with  a  simple  expression.  This  expression  is 
used  in  SWAN. 


Abreu  et  al.  (1992)  first  described  triad  wave-wave  interactions  in  terms  of  a  spectral  energy  source 
term.  However,  their  expression  is  restricted  to  non-dispersive  shallow  water  waves  and  is  not 
suitable  in  many  practical  wind  waves  applications.  A  breakthrough  came  from  Eldeberky  and 
Battjes  (1995),  who  transformed  the  amplitude  portion  of  the  Boussinesq  model  of  Madsen  and 
Sprensen  (1993)  into  an  energy  density  formulation  and  parameterized  the  biphase  of  the  waves  on 
the  basis  of  laboratory  observations  (Battjes  and  Beji,  1992;  Arcilla  et  al.,  1994).  A  discrete  triad 
approximation  (DTA)  for  co-linear  waves  was  subsequently  obtained  by  considering  only  the 
dominant  self-self  interactions.  Their  model  has  been  verified  with  flume  observations  of  long- 
crested,  random  waves  breaking  over  a  submerged  bar  (Beji  and  Battjes,  1993)  and  over  a  barred 
beach  (Arcilla  et  al.,  1994).  The  model  appeared  successful  in  describing  the  essential  features  of 
the  energy  transfer,  from  the  primary  peak  of  the  spectrum  to  the  super  harmonics.  Eldeberky 
(1996)  later  derived  a  slightly  different  version,  the  Lumped  Triad  Approximation  (LTA).  LTA  is 
used  in  SWAN. 


5.1.2  First-,  Second-  and  Third-generation  Mode 


SWAN  operates  in  first-,  second-  and  third-generation  mode.  The  first-  and  second-generation 
modes  are  essentially  those  of  Holthuijsen  and  de  Boer  (1988)  as  indicated  above,  with  the  first- 
generation  having  a  constant  Phillips  constant  of  0.0081  and  the  second-generation  a  variable 
Phillips  constant.  An  overview  of  the  options  is  given  below  in  Table  5.1-2. 


Table  5.1-2.  SWAN  Generation  Mode  Options. 


Generation  mode  of 
SWAN 

j  st  ^rd 

Linear  wind  growth:  Cavaleri  &  Malanotte-Rizzoli  (1981)  x  x 

[modified] 

Cavaleri  &  Malanotte-Rizzoli  (1981)  x 

Exponential  wind  growth:  Snyder  et  al.  ( 1 98 1 )  [modified]  x  x 

Snyder  et  al.  (1981)  x1 
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Janssen  (1989,  1991)  x2 

Holthuij  sen  and  de  Boer  (1988)  x3  x4 

Komen  et  al.  (1984)  x1 

Janssen  (1991),  Komen  et  al.  (1994)  x2 

Hasselmann  et  al.  (1985)  x 

Eldeberky  (1996)  x  x  x 

Battjes  &  Janssen  (1978)  x  x  x 

Hasselmann  et  al.  JONSWAP  (1973)  x  x  x 

Collins  (1972)  x  x  x 

Madsen  et  al.  (1988)  x  x  x 

Seelig  (1979)  x  x  x 

1  Gives  the  wind  input  and  whitecapping  formulations  as  used  in  WAM  Cycle  3  (see  Section 
4.12.9.3). 

2  Gives  the  wind  input  and  whitecapping  formulations  as  used  in  WAM  Cycle  4  (see  Section 
4.12.9.3). 

3  Pierson-Moskowitz  spectrum  as  upper  limit. 

4  Scaled  Pierson-Moskowitz  spectrum  as  upper  limit. 


Whitecapping: 


Quadruplet  interaction: 
Triad  interactions: 
Depth-induced  breaking: 
Bottom  friction: 


Obstacle  transmission: 


5.1.3  Wave-induced  Set-up 

The  computation  of  the  wave-induced  set-up  for  a  geographic  1-D  case  is  based  on  the  vertically 
integrated  momentum  balance  equation  that  reduces  to  a  balance  between  the  wave  radiation  stress 
gradient  and  the  hydrodynamic  pressure  gradient  (no  wave-induced  currents  exist).  In  a  2-D  case, 
the  computation  of  the  wave-induced  set-up  is  based  on  the  divergence  of  the  vertically  integrated 
momentum  balance  equation  equaling  zero. 


5.1.4  Detailed  Formulation 

The  following  sections  describe  the  expressions  for  the  physical  processes  of  generation,  dissipation 
and  nonlinear  wave-wave  interactions  available  in  SWAN. 


5.1.4.1  Input  by  Wind  (Si„) 

Wave  growth  by  wind  is  described  in  Section  5.1.1.2  by  equation  (2).  The  SWAN  model  is  driven 
by  the  wind  speed  at  10-m  elevation,  Ujo,  whereas  the  computations  use  the  friction  velocity  U*. 
For  the  WAM  Cycle  3  formulation  the  transformation  from  Ujo  to  U*  is  obtained  with: 

Ul=CDUl (7) 

in  which  Cp  is  the  drag  coefficient  from  Wu  (1982): 
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C„(uj= 


[  1.2875xlO~3  fort/I0  <  7.5  m/s 

{(0.8  +  0.065  s/m  x  (7I0 )  x  1 0-3  for  Ul0  >  7.5  m/s  ’ 


(8) 


For  the  WAM  Cycle  4  formulations,  the  computation  of  U*  is  an  integral  part  of  the  source  term. 


5.1.4.2  Linear  Growth  by  Wind: 


For  the  linear  growth  term  A,  the  expression  by  Cavaleri  and  Malanotte-Rizzoli  (1981)  is  used  with 
a  filter  to  eliminate  wave  growth  at  frequencies  lower  than  the  Pierson-Moskowitz  frequency 
(Tolman,  1992a)  (Note  that  in  Tolman’s  Eq.  9  the  10'5  should  be  10'3.  H.  Tolman,  personal 
communication,  1995): 


A  = 


l,5xl0~3 

g2 


[U,  max  [O,cos(0-0j]  ]4// 


(9) 


H  =  exp(-(cr/  o'PM  )“4)  with  a*  ={^2%-2  n  , 

rm  r\  r>  r  j  7 


in  which  Gh,  is  the  wind  direction,  H  is  the  filter  and  Qpm  is  the  peak  frequency  of  the  fully 
developed  sea  state  according  to  Pierson  and  Moskowitz  (1964;  reformulated  in  terms  of  friction 
velocity). 


5.1.4.3  Exponential  Growth  by  Wind: 


SWAN  has  two  expressions  for  exponential  growth  by  wind  optionally  available.  The  first  is  a 
Komen  et  al.  (1984)  expression  that  is  a  function  of  — : 


C 


ph 


B  =  max 

0,0.25^ 

28— ^-008(0-0  )  — 1 

1 

■g. 

1 _ _ 

(10) 


in  which  cph  is  the  phase  speed  and  pa  and  p,  are  the  density  of  air  and  water,  respectively.  This 
expression  is  also  used  in  WAM  Cycle  3  (the  WAMDI  group,  1988).  The  second  is  a  Janssen 
(1989,  1991)  expression  based  on  a  quasi-linear  wind-wave  theory  given  by: 


fU.  V 


\cpi'J 


max[o,  cos(0  -  0  w  )]2  <7 


(H) 
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where  (3  is  the  Miles  "constant".  In  the  theory  of  Janssen  (1991),  the  Miles  "constant"  is  estimated 
from  the  non-dimensional  critical  height  X: 


!( 

N>|  K) 

3 

■u 

X<1 

X=8Z2eer, 

r  =  fCc/\Ut  cos(0-0w)| 

'  ph 


(12) 


where  ris  the  Von  Karman  constant,  equal  to  0.41,  and  ze  is  the  effective  surface  roughness.  If  the 
non-dimensional  critical  height  X  >  1,  the  Miles  constant  /?  is  set  equal  to  zero.  Janssen  (1991) 
assumes  the  wind  profile  is  given  by: 


U(z)  =  —  ln| 

K 


z  +  ze-z0 


(13) 


in  which  U(z )  is  the  wind  speed  at  height  z  (10  m  for  SWAN)  above  the  mean  water  level, 
z0  is  the  roughness  length.  The  effective  roughness  length  ze  depends  on  the  roughness  length  z0 
and  the  sea  state  through  the  wave  induced  stress,  'CWt  and  the  total  surface  stress  T. 

ze=~.  h  -  and  z0=a ^  .  (14) 

^~TW/T  g 

The  second  of  these  two  equations  is  a  Chamock-like  relation  in  which  a  is  a  constant  equal  to 
0.01.  The  wave  stress  Tw  vector  is  given  by: 


Tw=pw]f<rBE(<T,Q)^dcrde 


(15) 


The  value  of  U*  can  be  determined  for  a  given  wind  speed,  U\q,  and  a  given  wave  spectrum, 

E(<j,  0),  from  the  above  set  of  equations.  The  iterative  procedure  of  Mastenbroek  et  al.  (1993)  is 
used  in  SWAN.  This  set  of  expressions  (Eq.  11-15)  is  also  used  in  WAM  Cycle  4  (Komen  et  al., 
1994). 

5.1.4.4  Dissipation  of  Wave  Energy  (S<js ) 

5.1.4.4.1  Whitecapping 

The  pulse-based  model  of  Hasselmann  (1974)  represents  the  processes  of  whitecapping  in  the 
SWAN  model.  Reformulated  in  terms  of  wave  number  rather  than  frequency  to  be  applicable  in 
finite  water  depth  (cf.  the  WAMDI  group,  1988),  this  expression  is  found  in  Section  5.1.1.3  under 
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equation  (3).  The  steepness  dependent  coefficient  (T),  as  given  by  the  WAMDI  group  (1988),  has 
been  adapted  by  Giinther  et  al.  (1992)  based  on  Janssen  (1991a,  see  Janssen,  1991b): 


r  =  r 


KJ 


'ds 


V 


(1  -S)  +  S~ 

k  J 


\  SPM 


(16) 


For  8=  0  the  expression  of  T  reduces  to  the  expression  as  used  by  the  WAMDI  group  (1988).  The 
coefficients  Cds,  <?and  m  are  tunable  coefficients,  s  is  the  overall  wave  steepness  (defined  below), 
sn)  is  the  value  of  s  for  the  Pierson-Moskowitz  spectrum  (1964;  sni  =  (3.02  x  10'3)'/2).  This 
overall  wave  steepness  s  is  defined  as: 

•  (i7) 


The  mean  frequency  & ,  the  mean  wave  number  k  ,  and  the  total  wave  energy  E,ol  are  defined  as 
(cf.  the  WAMDI  group,  1988): 


<7  = 


f  2/r°°  .  \  * 

K !  JJ-£(<7,0)d<rdO 


V  0  0 


(  2^00  \  2 

K  f  J-^£(o-,0)dad0 


Elgl  =  Jj£(<T,0)dcrd0  . 


0  0 


(18) 


(19) 


The  values  of  the  tunable  coefficients  Cjs  and  8 and  exponent  p  in  this  model  have  been  obtained  by 
Komen  et  al.  (1984)  and  Janssen  (1992)  by  closing  the  energy  balance  of  the  waves  in  idealized 
wave  growth  conditions  (both  for  growing  and  fully  developed  wind  seas)  for  deep  water.  This 
implies  that  coefficients  in  the  steepness  dependent  coefficient  F  depend  on  the  wind-input 
formulation  used.  Since  two  different  wind  input  formulations  are  used  in  the  SWAN  model,  two 
sets  of  coefficients  are  used.  For  the  wind  input  of  Komen  et  al.  (1984):  Cd,  =  2.36xlO'5,  <?=  0  and 
P~  4-  Janssen  (1992)  and  Gunther  (1992)  obtained  (assuming  p  =  4)  Cds  =  4. 10x1  O'5  and  8-  0.5 
(as  used  in  the  WAM  Cycle  4;  Komen  et  al.,  1994). 


5.1. 4.4.2  Bottom  Friction 

The  bottom  friction  models  that  have  been  selected  for  SWAN  are  the  empirical  model  of 
JONSWAP  (Hasselmann  et  al.,  1973),  the  drag  law  model  of  Collins  (1972)  and  the  eddy-viscosity 
model  of  Madsen  et  al.  (1988).  The  formulations  for  these  bottom  friction  models  can  all  be 
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expressed  in  the  form  of  equation  (4)  found  in  Section  5.1.13.  Cbottom  is  a  bottom  friction 
coefficient  that  generally  depends  on  the  bottom  orbital  motion  represented  by  Urm- 


U 


2 

rms 


27loo  ? 

f|— 2 - 

5  o  sinh2(fcd) 


E(cr,0)dcrde  . 


(20) 


Hasselmann  et  al.  (1973)  found  from  the  results  of  the  JONS  WAP  experiment 
Cbottom  =  Cjon  =  0.038  mV3  for  swell  conditions.  Bouws  and  Komen  (1983)  selected  a  bottom 
friction  coefficient  of  Cjon  =  0.067  m2s‘3  for  fully  developed  wave  conditions  in  shallow  water. 
Both  values  are  available  in  SWAN. 

The  expression  of  Collins  (1972)  is  based  on  a  conventional  formulation  for  periodic  waves  with 
the  appropriate  parameters  adapted  to  suit  a  random  wave  field.  The  dissipation  rate  is  calculated 
with  the  conventional  bottom  friction  formulation  of  Eq.  2,  in  which  the  bottom  friction  coefficient 
is  Cbottom  =  CjgUrms  with  Cf=  0.015.  Note  that  Collins  (1972)  contains  an  error  in  the  expression 
due  to  an  erroneous  Jacobean  transformation;  see  page  A- 16  of  Tolman,  1990. 

Madsen  et  al.  (1988)  derived  a  formulation  similar  to  that  of  Hasselmann  and  Collins  (1968),  but  in 
their  model  the  bottom  friction  factor  is  a  function  of  the  bottom  roughness  height  and  the  actual 
wave  conditions.  Their  bottom  friction  coefficient  is  given  by: 


=  f  -£—U 

''bottom  J  w  r 


(21) 


in  which  fw  is  a  non-dimensional  friction  factor  estimated  by  using  the  formulation  of  Jonsson 
(1966;  cf.  Madsen  et  al.,  1988): 


=  mf  +log]0 


(22) 


in  which  m/=  -  0.08  (Jonsson  and  Carlsen,  1976)  and  cib  is  a  representative  near-bottom  excursion 
amplitude: 


27Too 

al=2\\  ■  ,,  "-g(<M)d<7de  ,  (23) 

smh  (kd) 

and  Kn  is  the  bottom  roughness  length  scale.  For  values  of  a.b  /  KN  smaller  than  1.57  the  friction 
factor  fw  is  0.30  (Jonsson,  1980). 
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5.L4.4.3  Depth-induced  Wave  Breaking 


To  model  the  energy  dissipation  in  random  waves  due  to  depth-induced  breaking,  SWAN  uses  the 
bore-based  model  of  Battjes  and  Janssen  (1978).  The  mean  rate  of  energy  dissipation  per  unit 
horizontal  area  due  to  wave  breaking  Dtot  is  expressed  as: 


(24) 


in  which  Gfaj  -  1  in  SWAN,  Qt,  is  the  fraction  of  breaking  waves  determined  by: 

o Em. 

In  Q„  Hi  ’ 


(25) 


in  which  Hm  is  the  maximum  wave  height  that  can  exist  at  the  given  depth  and  o  is  a  mean 
frequency  defined  as: 


2^oo 

0  0 


(26) 


Extending  the  expression  of  Eldeberky  and  Battjes  (1995)  to  include  the  spectral  directions,  the 
dissipation  for  a  spectral  component  per  unit  time  is  calculated  with  equation  (5)  in  Section  5.1.1.3, 

The  maximum  wave  height,  Hm,  is  determined  with  Hm  =  yd,  in  which  y  is  the  breaker  parameter 
and  d  is  the  total  water  depth  including  the  wave-induced  set-up  if  computed  by  SWAN.  In  the 
literature,  this  breaker  parameter  y  is  often  a  constant  or  it  is  expressed  as  a  function  of  bottom 
slope  or  incident  wave  steepness  (see  Galvin,  1972;  Battjes  and  Janssen,  1978;  Battjes  and  Stive, 
1985;  Arcilla  and  Lemos,  1990;  Kaminsky  and  Kraus,  1993;  Nelson,  1987,  1994).  Since  SWAN  is 
locally  defined,  the  dependency  on  incident  wave  steepness  cannot  be  used.  Instead,  the  constant 
value  or  bottom-slope  dependent  options  are  used  in  all  SWAN  versions  to  determine  the  value  of 
the  breaker  parameter.  In  SWAN  Version  40. 1 1 ,  the  option  of  Nelson  has  been  removed,  as  the 
results  of  SWAN  are  better  with  the  option  of  a  constant  value. 

In  the  dissipation  model  description  of  Battjes  and  Janssen  (1978)  a  constant  breaker  parameter  of  y 
=  0.8  was  used  based  on  Miche's  criterion.  Battjes  and  Stive  (1985)  re-analyzed  laboratory  and 
field  wave  data  and  found  values  for  the  breaker  parameter  varying  between  0.6  and  0.83  for 
varying  bathymetry  (plane,  bar-trough  and  bar)  with  an  average  of  0.73.  Kaminsky  and  Kraus 
(1993)  found  breaker  parameters  in  the  range  of  0.6  to  1.59  with  an  average  of  0.79. 
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5.1.4.5  Nonlinear  Wave-wave  Interactions  (S„j ) 

5.1.4.5.1  Quadruplet  Wave-wave  Interactions 

The  quadruplet  wave-wave  interactions  are  computed  with  the  Discrete  Interaction  Approximation 
(DIA)  as  proposed  by  Hasselmann  et  al.  (1985).  Their  source  code  (slightly  adapted  by  Tolman, 
personal  communication,  1993)  has  been  used  in  the  SWAN  model.  In  DIA  two  quadruplets  of 
wave  numbers  are  considered,  both  with  frequencies: 


CJ  j  (J  2  ^ 

<J3  =  <7(  1  +  A)  =  <r+  ,  (27) 

cr4  =  a(l  -X)  =  a~ 

where  X  is  a  constant  coefficient  set  equal  to  0.25.  To  satisfy  the  resonance  conditions  for  the  first 
quadruplet,  the  wave  number  vectors  with  frequency  <7$  and  o4  lie  at  an  angle  of  0i  =  -  1 1.5°  and 
02  =  33.6°  to  the  two  identical  wave  number  vectors  with  frequencies  <7!  and  02.  The  second 
quadruplet  is  the  mirror  of  this  first  quadruplet  (the  wave  number  vectors  with  frequency  03  and  04 
lie  at  mirror  angles  of  03  =  1 1.5°  and  04  =  -  33.6°). 

Within  DIA,  the  source  term  Sni4  (a,  0  )  is  given  by: 

snl4  (<r,  G) = s;,4  (o-,  0) + s;;4  (<x,  0)  ,  (28) 


where  S*l4  refers  to  the  first  quadruplet  and  S*n*l4  to  the  second  quadruplet  (the  expressions  for  S**4 
are  identical  to  those  for  S*nl4  for  the  mirror  directions)  and 


Sn*/4  (<r,  0)  =  2  S  Snl4  {a,  o’,  0)  -  5  Snl4  (a2c 7, 0)  -  S  Snl4  ( a3 cr,  0)  , 


(29) 


where  a.\  =  1,  Oi  =  (1  +  A,)  and  =  (1  -  X).  Each  of  the  contributions  (i  =  1,  2,  3)  is: 


4S.„(a,<7,e)  =  C.,4( 


2  — 4 1  G 


2 it . 


E2(«,.(7,0) 


£'(or,£7+,0)  E{atG  ,0) 
(1 +  X)4  +  (l-X)4 


E(aicj,Q)E(aicr+ ,0) 


2x4 


d-i2) 


•  (30) 


The  constant  C„«  =  3xl07.  Following  Hasselmann  and  Hasselmann  (1981),  the  quadruplet 
interaction  in  finite  water  depth  is  taken  identical  to  the  quadruplet  transfer  in  deep  water  multiplied 
with  a  scaling  factor  R: 
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s 


nl  4,  finite  depth 


R(kpd)S 


nl  A, \n finite  depth 


where  R  is  given  by: 


(31) 


R(kpd)  =  \+£dL(\-Csh2-kpd)c\p{cM-kpd)  ,  (32) 

in  which  kp  is  the  peak  wave  number  of  the  JONSWAP  spectrum  for  which  the  original 
computations  were  carried  out.  The  values  of  the  coefficients  are  CshI  =  5.5,  C,h2  =  6/7  and 
Csh3  =  - 1-25.  In  the  shallow  water  limit,  i.e.,  kpd  — >  0,  the  nonlinear  transfer  tends  towards  infinity. 
Therefore  a  lower  limit  of  kpd  =  0.5  is  applied,  resulting  in  a  maximum  value  of  R(kpd )  =  4.43.  To 
increase  the  model  robustness  in  case  of  arbitrarily  shaped  spectra,  the  peak  wave  number  kp  is 
replaced  by  kp  =0.75 k  (Komen  et  al.,  1994). 

5.1.4.5.2  Triad  Wave-wave  Interactions 


The  Lumped  Triad  Approximation  (LTA)  of  Eldeberky  (1996),  a  slightly  adapted  version  of  the 
Discrete  Triad  Approximation  of  Eldeberky  and  Battjes  (1995),  is  used  in  SWAN  in  each  spectral 
direction: 


Sn,  3  (0-,  e)  =  5-3  (<7, 0)  +  s*  3  (a,  0) 


(33) 


with 


•Sn+,3  (0\  0)  =  max  {  0,  aEB  2  nccR  J 2 1  sin(y9)|  {e 2  (a  /  2, 0)  -  2  E(o  /  2, 0)  E{o,  0) }}  (34) 

and  5„,3(ct,0)  =  -25;/3(2(T,0)  (35) 

in  which  oceb  is  a  tunable  proportionality  coefficient.  The  biphase  /?is  approximated  with 


a  n  n  ( 0.2^ 

//  = - +— tanh  — 

2  2  \Ur  j 


(36) 


with  Ursell  number  Ur 


Ur.-fUL£ 

d2 


(37) 


with  T  -2n  I o  .  The  triad  wave-wave  interactions  are  calculated  only  for  10  >  Ur  >  0. 1 .  The 
interaction  coefficient  J  is  taken  from  Madsen  and  Sprensen  (1993): 
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7  = 


^012(8  d  +  2ca/2) 


kad(gd+-gdX 


-<r2d2 

5 


(38) 


5.1.4.5.3  Wave-induced  Set-up 


In  a  geographic  1  -D  case  the  wave  induced  set-up  computation  is  based  on  the  vertically  integrated 
momentum  balance  equation.  It  is  a  balance  between  the  wave  force  (gradient  of  the  wave  radiation 
stress  normal  to  the  coast)  and  the  hydrodynamic  pressure  gradient  (note  that  the  component 
parallel  to  the  coast  causes  wave-induced  currents  but  no  setup): 

0.  <39> 


where  d  is  the  total  water  depth  and  77  is  the  mean  surface  elevation.  Both  d  and  f]  include  wave- 
induced  set-up. 


Computations  based  on  the  vertically  integrated  momentum  balance  equation  of  Dingemans  et  al. 
(1987)  show  that  the  wave-induced  currents  are  driven  by  the  divergence-free  portion  of  the  wave 
forces,  whereas  the  set-up  is  mainly  due  to  the  rotation-free  part  of  these  forces.  To  compute  the 
set-up,  it  is  sufficient  to  consider  the  divergence  of  the  momentum  balance  equation.  If  the 
divergence  of  the  acceleration  in  the  resulting  equation  is  ignored,  the  result  is: 


dFx  dFv  a 
— ^  +  — -  +  — 
dx  dy  ox 


\ 

J 


=  0  . 


(40) 


5.2  Numerical  Implementation 

The  integration  of  the  action  balance  equation  has  been  implemented  in  SWAN  with  finite 
difference  schemes  in  all  dimensions  including  time,  geographic  space  and  spectral  space.  These 
are  first  described  for  wave  propagation  without  source  terms  for  generation,  dissipation  and  wave- 
wave  interactions.  Then  the  implementation  of  these  source  terms  is  described. 

Time  is  discretized  with  a  simple  constant  time  step.  At,  for  the  simultaneous  integration  of  the 
propagation  and  the  source  terms.  In  WAM  and  WAVEWATCH  the  propagation  time  step  is 
different  from  the  time  step  for  the  source  terms.  Geographic  space  is  discretized  with  a  rectangular 
grid  with  constant  resolutions  Ax  and  Ay  in  x-  and  y-direction,  respectively.  In  fact,  this  rectangular 
grid  is  a  special  case  of  the  curvilinear  grid  programmed  in  SWAN.  The  spectrum  in  the  model  is 
discretized  with  a  constant  directional  resolution  A0  and  a  constant  relative  frequency  resolution 
A  cr/er  (logarithmic  frequency  distribution).  For  reasons  of  economy,  an  option  is  available  to 
compute  only  wave  components  traveling  in  a  pre-defined  directional  sector  (9min  <  0  <  0max;  e.g., 
those  components  that  travel  shoreward  within  a  limited  directional  sector).  The  discrete 
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frequencies  are  defined  between  a  fixed  low-frequency  cut-off  and  a  fixed  high-frequency  cut-off. 
For  these  frequencies  the  spectral  density  is  unconstrained.  Below  the  low-frequency  cut-off,  which 
is  typically =  0.04  Hz  for  field  conditions,  the  spectral  densities  are  assumed  to  be  zero.  Above 
the  high-frequency  cut-off,  typically  1  Hz  for  field  conditions,  a  diagnostic  tail  fm  is  added.  This 
tail  is  used  to  compute  nonlinear  wave-wave  interactions  at  the  high  frequencies  and  compute 
integral  wave  parameters.  The  reason  for  using  a  fixed  high-frequency  rather  than  a  dynamic  cut¬ 
off  frequency  that  depends  on  the  wind  speed  or  on  the  mean  frequency,  as  in  WAM  and 
WAVEWATCH  ID,  is  that  in  coastal  regions  mixed  sea  states  with  different  characteristic 
frequencies  may  occur.  For  instance,  a  local  wind  may  generate  a  very  young  sea  behind  an  island, 
totally  unrelated  to  (but  superimposed  on)  a  simultaneously  occurring  swell.  In  such  cases  a 
dynamic  cut-off  frequency  may  be  too  low  to  properly  account  for  the  locally  generated  sea  state. 
Based  on  physical  arguments  the  value  of  m  (the  power  of  the  spectral  tail)  should  be  between  4  and 
5  (e.g.,  Phillips,  1985).  In  SWAN  m  =  4  if  the  wind  input  formulation  of  Komen  et  al.  (1984)  is 
used  (cf.  WAM  Cycle  3),  and  m  =  5  if  the  wind  input  formulation  of  Janssen  (1991a)  is  used 
(WAM  Cycle  4). 

5.2.1  Propagation 


The  numerical  schemes  in  SWAN  have  been  chosen  on  the  basis  of  robustness,  accuracy  and 
economy.  Since  the  nature  of  the  basic  equation  is  such  that  the  state  in  a  grid  point  is  determined 
by  the  state  in  the  upwave  grid  points,  the  most  robust  scheme  would  be  an  implicit  upwind 
scheme,  in  both  geographic  and  spectral  space.  The  term  "implicit"  is  used  to  indicate  that  all 
derivatives  of  action  density  (in  t,  x  or  y)  are  formulated  at  one  computational  level,  i,  or  ix  or  iy, 
except  for  the  integration  dimension  derivative  for  which  the  previous  or  upwave  level  is  used  (time 
in  non-stationary  mode  and  x  or  y  in  stationary  mode).  For  such  a  scheme  the  values  of  the  time 
and  space  steps  At,  Ax,  and  Ay  are  mutually  independent.  An  implicit  scheme  would  also  be 
economical  because  the  scheme  is  unconditionally  stable.  It  permits  relatively  large  time  steps  in 
the  computations,  much  larger  than  for  explicit  schemes  in  shallow  water.  Using  the  second- 
generation  HISWA  shallow  water  wave  model,  Holthuijsen  et  al.,  1989  showed  that  for  coastal 
regions  a  first-order  upwind  difference  scheme  in  geographic  space  is  sufficiently  accurate.  This 
observation,  together  with  SWAN  test  runs,  has  also  shown  that  in  spectral  space  a  higher  accuracy 
than  that  of  a  first-order  upwind  scheme  is  required.  This  can  be  achieved  by  supplementing  with  a 
second-order  central  approximation,  which  is  more  economic  than  a  second-order  upwind  scheme. 
For  SWAN  therefore,  implicit  upwind  schemes  in  both  geographic  and  spectral  space  have  been 
chosen,  supplemented  with  a  central  approximation  in  spectral  space. 

The  state  in  a  grid  point  is  determined  by  the  state  in  the  upwave  grid  points  as  defined  by  the 
direction  of  propagation.  This  permits  a  decomposition  of  the  spectral  space  into  four  quadrants 
(eight  octants  would  be  an  alternative).  In  each  of  the  quadrants  the  computations  may  be  carried 
out  independently  except  for  the  interactions  between  them  due  to  refraction  and  nonlinear  wave- 
wave  interactions  (formulated  in  corresponding  boundary  conditions  between  the  quadrants).  The 
wave  components  in  SWAN  are  correspondingly  propagated  in  geographic  space  with  an  upwind 
scheme  (“upwind”  is  the  commonly  used  term  in  numerical  analysis,  but  “upwave”  would  be  more 
appropriate  in  the  case  of  SWAN).  SWAN  contains  three  such  schemes: 
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a.  First-order  (stationary  and  non-stationary  cases)  backward  space-backward  time:  the 
BSBT  scheme, 

b.  Second-order  (non-stationary  cases)  with  third-order  diffusion:  the  S&L-scheme  (Stelling 
and  Leedertse,  1992), 

c.  Second-order  (stationary  cases)  with  second-order  diffusion:  the  SORDUP  scheme. 

The  first-order  upwind  BSBT  scheme  is  not  default  in  SWAN.  It  is  a  sequence  of  four  forward¬ 
marching  sweeps  (one  per  quadrant).  To  properly  account  for  the  boundary  conditions  between  the 
four  quadrants,  the  computations  are  carried  out  iteratively  at  each  time  step.  The  integration  in 
time  is  a  simple  backward  finite  difference,  so  that  the  discretization  of  the  action  balance  equation 
is  as  follows  for  positive  propagation  speeds  including  the  computation  of  the  source  terms  but 
ignoring  their  discretization: 
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where  i,  is  the  time-level  index,  ix,  iy,  ia  and  i%  are  grid  counters,  and  At,  Ax,  Ay,  Act,  and  A0  are  the 
increments  in  time,  geographic  space  and  spectral  space,  respectively.  The  iterative  nature  of  the 
computation  is  indicated  with  the  iteration  index  n  (the  iteration  index  for  the  source  terms  n*  is 
equal  to  n  or  n-l,  depending  on  the  source  term.  See  below).  Because  of  these  iterations,  the 
scheme  is  also  approximately  implicit  for  the  source  terms.  For  negative  propagation  speeds, 
appropriate  +  and  -  signs  are  required  in  Eq.  41. 

The  coefficients  vand  rj  determine  the  degree  to  which  the  scheme  in  spectral  space  is  upwind  or 
central.  They  control  the  numerical  diffusion  in  frequency  and  directional  space,  respectively.  A 
value  of  v=  0  or  ij  -  0  corresponds  to  central  schemes  which  have  the  largest  accuracy  (numerical 
diffusion  =  0).  Values  of  v=  1  or  77=  1  correspond  to  upwind  schemes  which  are  somewhat  more 
robust  and  diffusive  and  therefore  less  accurate.  If  large  gradients  of  the  action  density  in  frequency 
space  or  directional  space  are  present,  numerical  oscillations  may  arise,  especially  with  the  central 
difference  schemes,  resulting  in  negative  action  density  values.  In  each  sweep  such  negative  values 
are  removed  from  the  two-dimensional  spectrum  by  setting  these  values  equal  to  zero  and  re-scaling 
the  remaining  positive  values  such  that  the  frequency-integrated  action  density  per  spectral  direction 
is  conserved.  The  depth  derivatives  and  current  derivatives  in  the  expressions  of  ca  and  cq  are 
calculated  with  a  first-order  upwind  scheme.  For  very  strong  refraction  the  value  of  ce  is  reduced  in 
each  grid  point  and  each  wave  component  individually  with  the  square  of  the  fraction  of  the  grid 
spacing  over  which  kd  <  3.0. 
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For  stationary  conditions  SWAN  may  be  run  in  stationary  mode.  Time  is  removed  as  a  variable  but 
the  integration  in  geographic  space  is  still  carried  out  iteratively.  The  propagation  scheme  is  still 
implicit  as  the  derivatives  of  action  density  (in  x  or  y)  at  the  computational  level  (ix  or  iy  , 
respectively)  are  formulated  at  that  level  except  in  the  integration  dimension,  (x  or  y;  depending  on 

the  direction  of  propagation)  where  the  upwave  level  is  used.  The  values  of  Ax  and  Ay  are  therefore 
still  mutually  independent. 

For  the  stationary  second-order  upwind  scheme  (Rogers  et  al„  2000)  which  is  the  default  scheme 

for  stationary  computations,  the  two  terms  in  Eq.  41  representing  x-  and  y-derivatives  are  replaced 
by: 
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For  the  nonstationary  second-order  upwind  scheme  (Rogers  et  al.,  2000;  S  and  L  =  Stelling  and 
Leendertse),  which  is  the  default  scheme  for  nonstationary  computations,  the  two  terms  in  Eq.  41 
representing  x-  and  y-derivatives  are  replaced  by: 
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To  explain  the  above  numerical  solution  technique  in  terms  of  matrix  solutions,  first  ignore  the 
decomposition  in  quadrants.  The  propagation  of  the  waves  in  both  geographic  and  spectral  space 
would  then  be  described  with  one  large  basic  matrix  that  can  be  solved  in  several  ways.  Removing 
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refraction,  frequency  shifting  and  nonlinear  source  terms  from  this  basic  matrix  permits  a  matrix 
solution  with  a  Gauss-Seidel  technique  (e.g.,  Golub  and  van  Loan,  1986)  in  which  the  matrix  is 
decomposed  in  four  sections  (the  above  four  directional  quadrants)  that  are  each  solved  in  one  step 
(super-convergence).  Restoring  refraction  and  frequency  shifting  to  the  matrix  requires  the  solution 
of  a  submatrix  for  each  geographic  grid  point.  If  no  currents  are  present  and  the  depth  is  stationary, 
this  is  readily  done  with  a  Thomas  algorithm  (e.g.,  Abbott  and  Basco,  1989;  cff=  0  and  the  sub¬ 
matrix  is  a  simple  tri-diagonal  matrix).  If  currents  are  present  or  the  depth  is  not  stationary,  the  sub¬ 
matrix  is  a  band  matrix.  It  is  solved  with  an  iterative  ILU-CGSTAB  method  (Vuik,  1993;  Van  der 
Vorst,  1992).  Restoring  refraction  and  frequency-shifting  also  introduces  coefficients  in  each 
matrix  section  (directional  quadrant)  that  cause  dependency  between  the  sections.  The  same 
happens  when  nonlinear  source  terms  are  added  to  the  matrix.  The  basic  matrix  as  a  whole  must  be 
solved  iteratively  until  some  break-off  criteria  are  met.  To  reduce  the  number  of  iterations  in 
stationary  mode  with  wind  generation,  SWAN  begins  with  a  reasonable  first-guess  of  the  wave 
field,  a  "quickstart"  based  on  the  second-generation  source  terms  of  Holthuijsen  and  De  Boer,  1988, 
adapted  for  shallow  water.  It  reduces  the  number  of  iterations  typically  by  a  factor  two.  In 
nonstationary  mode,  a  very  reasonable  first-guess  per  time  step  is  available  from  the  previous  time 
step  and  the  number  of  iterations  is  expected  to  be  small.  If  no  iterations  are  used  in  nonstationary 
mode  (as  in  most  phase  averaged  wave  models),  the  computations  of  propagation  are  still  implicit 
and  therefore  still  unconditionally  stable. 

For  grid  points  that  represent  open  boundaries,  land  boundaries  and  obstacles,  these  being  the  last 
two  grids  adjoining  such  grid  points  for  the  SORDUP  scheme  and  the  last  three  grids  adjoining 
such  grid  points  for  the  S&L  scheme,  SWAN  will  revert  to  the  first-order  BSBT  scheme.  This 
scheme  has  a  larger  numerical  diffusion  that  is  usually  acceptable  over  the  small  distances  involved. 

The  numerical  diffusion  of  the  S&L  scheme  is  so  small  that  the  so-called  garden-sprinkler  effect 
(GSE)  may  appear  if  propagation  over  very  large  distances  is  considered.  GSE  is  due  to  spectral 
resolution  (see  Booij  and  Holthuijsen,  1987)  and  can  be  counteracted  by  a  diffusion  term  explicitly 
added  to  the  numerical  scheme  (not  default  in  SWAN).  Its  value  depends  on  the  spectral  resolution 
and  the  propagation  time  of  the  waves  (see  the  input  variable  [wave  age]  in  the  SCHEME 
command). 

The  diffusion  applied  in  the  propagation  direction  is: 

Dss  =  Ac2T  /  12,  (42) 

where  T  is  the  wave  age. 

The  diffusion  normal  to  the  propagation  direction  is: 

Dss  =  c2AQ2T  /  12.  (43) 

From  these  diffusion  coefficients  (in  terms  of  x  and  y)  are  calculated: 

Dxx  =  Dssc  os29  +  D„„sin20; 
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Dyy  =  £>„sin26  +Dn„  cos20; 
Dxy  =  (D„  -  D,m)  cos0sin0. 


(44) 


The  diffusion  terms  are  computed  at  the  time  level  i,-  1 .  The  diffusion  terms  are  computed  as 
follows: 
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This  explicit  finite  differencing  is  fast  (having  little  impact  on  computation  time)  but  only 
conditionally  stable.  Through  mathematical  analysis  (not  shown)  it  can  be  shown  that  a  likely 
stability  condition  for  the  one-dimensional  S&L  scheme  with  a  GSE  correction  is  DAt/(Ax2)  <  0.5, 
corresponding  to  the  two-dimensional  stability  criterion  of  Tolman  (1995): 


max( 
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(46) 


Eq.  46  holds  true  for  the  two-dimensional  S  and  L  scheme  with  a  GSE  correction.  In  experiments, 
instability  was  observed  for  experiments  that  satisfied  the  slightly  more  restrictive  Q  <  0.48.  In 
short,  by  adding  the  GSE  correction,  the  unconditionally  stable  advection  scheme  of  SWAN 
becomes  a  (likely)  conditionally  stable  advection  diffusion  scheme.  For  typical  ocean  applications 
Dnn  dominates  the  diffusion  and  can  be  written  as: 


Q  =  CT  /  Ax.CAt/ Ar.A02 /12.  (47) 

The  variable  wave  age  T  could  be  computed  during  SWAN  computations  (Booij  and  Holthuijsen, 
1987)  but  requires  the  same  order  of  magnitude  of  computer  memory  as  integrating  the  action 

balance  equation.  Instead,  a  constant  wave  age  T  may  be  used  as  an  approximation  so  that  Eq.  47 
becomes 


Q-LI  Ax//.A0/12,  (4g) 

where  the  characteristic  travel  distance  of  the  waves  is  I  =  Cf  (e.g.,  the  dimension  of  the  ocean 
basin).  For  oceanic  applications  the  Courant  number  is  typically  fi~V. i  so  that  Q  <  0.25  for  typical 
values  of  A0  and  L  /Ax  (the  number  of  grid  points  in  one  direction  of  the  grid).  This  implies  that  an 
S&L  scheme  with  GSE  correction  is  stable  for  typical  ocean  cases.  For  shelf  sea  (regional) 
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applications  the  value  of  ju  =  0(1)  but  GSE  tends  to  be  small  on  these  scales  and  the  diffusion  must 
not  be  used  to  avoid  the  stability  problem.  For  small-scale  (local)  applications  ju  =  0(10-100).  Such 
cases  are  usually  treated  as  stationary,  and  the  SORDUP  scheme  should  be  used  (no  GSE  correction 
is  included  in  this  scheme). 

The  boundary  conditions  in  SWAN,  both  in  geographic  and  spectral  space,  are  fully  absorbing  for 
wave  energy  leaving  the  computational  domain  or  crossing  a  coastline.  The  incoming  wave  energy 
along  open  geographic  boundaries  must  be  prescribed  by  the  user.  For  coastal  regions  incoming 
energy  is  provided  only  along  the  deep-water  boundary  and  not  along  the  lateral  geographic 
boundaries  (i.e.,  the  spectral  densities  are  assumed  to  be  zero).  This  implies  that  such  erroneous 
lateral  boundary  conditions  are  propagated  into  the  computational  area.  The  affected  areas  are 
typically  triangular  regions  with  the  apex  at  the  comers  between  the  deep-water  boundary  and  the 
lateral  boundaries.  The  areas  spread  towards  shore  at  an  angle  of  30°  to  45°  for  wind  sea  conditions 
on  either  side  of  the  deep-water  mean  wave  direction.  The  angle  is  less  for  swell  conditions  and  is 
essentially  equal  to  the  one-sided  width  of  the  directional  distribution  of  the  incoming  wave 
spectrum.  Therefore,  the  lateral  boundaries  should  be  sufficiently  far  away  from  the  area  of  interest 
to  avoid  the  propagation  of  this  error  into  the  area. 


5.2.1. 1  Generation,  Wave-wave  Interactions  and  Dissipation 

The  numerical  estimations  of  the  source  terms  in  SWAN  are  essentially  implicit.  This  is  achieved 
with  explicit  or  implicit  approximations  of  the  source  terms,  which  in  the  limit  of  a  large  number  of 
iterations,  always  result  in  an  implicit  estimation.  In  actual  computations  final  convergence  is  never 
achieved,  and  the  estimations  of  the  source  terms  are  only  approximately  implicit.  In  the  following 
description,  the  adjectives  "explicit"  and  "implicit"  refer  to  the  approximations  of  the  source  terms 
within  each  iteration. 

The  linear  growth  term  A  is  independent  of  integral  wave  parameters  and  the  energy  density  and  can 
therefore  be  readily  computed.  All  other  source  terms  depend  on  energy  density  and  can  be 
described  as  (quasi-)  linear  terms:  S  =  §E,  in  which  <f)  is  a  coefficient  that  depends  on  (integral) 
wave  parameters  such  as  Etot,  o,  k,  o,  k,  and  action  densities  of  other  spectral  components.  Since 
these  are  only  known  at  the  previous  iteration  level  n-1,  the  coefficient  is  determined  at  that 
iteration  level:  <()  =  (j)"1. 

For  positive  source  terms  (wind  input  and  the  triad  wave-wave  interactions  if  positive)  the 
integration  is  generally  more  stable  if  an  explicit  formulation  is  used  (i.e.,  the  source  term  depends 
on  £"'!  and  not  on  £”)  rather  than  an  implicit  formulation  (i.e.,  the  source  term  also  depends  on  En). 
The  explicit  formulation  for  these  source  terms  in  SWAN  is  therefore: 

S"  «  f'ET1  (49) 

The  explicit  approximation  is  also  used  for  the  formulation  of  the  quadruplet  wave-wave 
interactions  for  both  the  positive  and  negative  contributions.  Tolman  (1992a)  has  shown  that  using 
an  explicit  formulation  in  combination  with  a  limiter  (see  below)  gives  results  similar  to  using  a 
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more  expensive  implicit  scheme.  The  implicit  formulation  is  optionally  available  in  SWAN  and  is 
indicated  as  the  semi-implicit  scheme  in  WAM  (The  WAMDI  group,  1988;  Komen  et  al,  1994). 

For  negative  source  terms  the  integration  is  more  stable  if  an  implicit  scheme  is  used.  The  strongly 
nonlinear,  negative  source  term  of  depth-induced  wave  breaking  at  iteration  level  n  is  accordingly 
estimated  with  a  linear  approximation: 


5"  =  (J)"'1  £"■'  + 


rasY"1 
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(50) 


However,  to  achieve  even  more  stable  computations  for  this  source  term,  the  term 
4*  F”  in  this  formulation  has  been  replaced  by  <{>"  1 E n  ,  thus  making  the  formulation  somewhat 
more  implicit  and  robust.  Note  that  the  solution  in  the  limit  is  the  same.  Since  the  process  of 
depth-induced  wave  breaking  has  been  formulated  such  that  S  =  aSm  and  E  =  aEtot,  the  derivative  is 
dS/BE  analytically  determined  as  dSlot  /dElol  (where  is  a  identical  in  both  expressions  and  the  total 

energy  Elo,  and  the  total  source  S,„,  are  the  integrals  over  all  frequencies  and  directions  of  E{a,  0 ) 
and  Sds b^CT,  0),  respectively).  For  other  negative  (mildly  nonlinear)  source  terms  such  as 
whitecapping,  bottom  friction  and  negative  triad  wave-wave  interactions,  a  similar  accuracy  of 
estimating  S"  can  be  achieved  with  the  following  simpler  more  economical  approximation  in  which 
(dS /dE)n~l  of  Eq.  13  has  been  replaced  by  (S/E)"'1 


sr  =  (j)"'1  et]+ 
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(51) 


With  S  =  <])E,  this  reduces  to: 


sr  s  e" 


(52) 


The  approximations  for  the  source  terms  are  added  to  the  matrix  elements  for  the  propagation.  To 
suppress  the  development  of  numerical  instabilities,  the  maximum  total  change  of  action  density 
per  iteration  at  each  discrete  wave  component  is  limited  to  a  fraction  of  10%  of  the  Phillips  (1957) 
equilibrium  level.  It  is  reformulated  in  terms  of  action  density  and  wave  number  to  be  applicable  in 
shallow  water,  as  in  WAM  and  WAVEWATCH  m  (Tolman,  1 992a): 


0. 1  Ctp^  7t_ 
2na  k3c 


(53) 


where  =  0.0081  is  the  Phillips'  "constant"  of  the  Pierson-Moskowitz  (1964)  spectrum.  To 
retain  the  very  rapid  but  realistic  decrease  of  wave  energy  near  the  shore  due  to  depth-induced  wave 
breaking  this  limiter  is  not  applied  if  the  waves  actually  break.  In  SWAN,  HrJHm „  <  0.2  with 

Hrms  =  yjZEuo,  ,  Which  implies  a  fraction  of  breakers  Qb  >  0.00001 . 


The  fraction  of  depth-induced  breakers  (Qh)  is  determined  in  SWAN  with 
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&= 0 

for  0<O.2 

„  „  „2e„-exp«e0-i)//i2) 

Ub  Vo  P  p2  _exp((g0  -I)//?2) 

for  0.2  <  0  <  l 

(one  step  Newton-Raphson  iteration) 

Qb=  1 

for  0=1 

where  0=  H„JHmax .  For  0<  0.5,  Q0  =  1,  and  for  0.5  <0<\,Qo  =  (20-  if. 

(54) 


5.2.1.2  Wave-induced  Set-up 

In  1-D  cases  the  wave-induced  set-up  is  calculated  with  a  simple  trapezoidal  rule. 

In  2-D  cases  the  Poisson  equation  of  the  divergence-free  force  field  is  solved  using  the  same  solver 
employed  for  wave  propagation  with  ambient  currents.  The  boundary  conditions  for  the  elliptical 
partial  differential  equation  are: 

Non-nested  computations: 

•  At  open  boundaries,  the  equilibrium  between  wave  force  and  hydrodynamic  pressure 
gradient  is  normal  to  the  model  boundary; 

•  At  the  last  grid  points  before  shoreline,  the  equilibrium  between  wave  force  and 
hydrodynamic  pressure  gradient  is  normal  to  the  model  boundary; 

•  At  deepest  boundary  point,  the  set-up  is  zero. 

Nested  computations: 

•  At  open  boundaries,  the  set-up  is  taken  from  the  larger  computation, 

•  At  last  grid  points  before  shoreline,  the  equilibrium  between  wave  force  and  hydrodynamic 
pressure  gradient  is  normal  to  the  model  boundary. 

The  shoreline  in  SWAN  moves  as  dictated  by  the  wave-induced  set-up.  The  set-up  computations 
are  available  on  both  the  rectilinear  and  curvilinear  grids. 


5.2.1.3  Curvilinear  Grid 

SWAN’s  propagation  scheme  for  geographic  space  is  formulated  on  a  curvilinear  geographic  grid 
(irregular,  quadrangular,  and  not  necessarily  orthogonal)  rather  than  the  rectilinear  grid  of  SWAN 
Cycle  1 .  This  modification  is  based  on  approximating  the  geographic  distribution  of  the  energy 
action  density  between  each  three  neighboring  grid  points  with  a  flat  triangle.  The  gradient  in  each 
grid  point  at  location  (xj,  yj)  is  then  readily  approximated  from  the  upwind  grid  points.  For  the  x- 
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direction  this  approximation  is  for  grid  point  i,  j  (the  grid  points  are  ordered  in  x,  y-space  with 
labels  i  and  j\  respectively): 


3C,N 

dx 


_L 

Ax, 

r 

1 

& 

NJ 

l  -  -  -3 

(55) 


where  Ax,  -  Ax,  -  (Ay,  /  A y2 )Ax2 ,  Ax2  -  Ax2  -  (Ay2  /  Ay,  )Ax, .  The  increments  are  Axi  =  xt  J  - x,-.j , 

^•2  —  X>J  _  j  Ayi  =  )'<.  I  ~  y’i-ij  a°d  Ay2  =  Vi,  j  —  yt,  j  i ■  The  gradient  in  y-direction  is  similarly 
estimated. 
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Appendix  A  Command  syntax 

It  is  important  distinguish  between  the  description  of  the  commands  in  this  manual  and  the  actual 
commands  in  the  command  file.  The  descriptions  of  the  commands  are  called  command  schemes. 
Each  such  command  scheme  includes  a  diagram  and  a  description  explaining  the  structure  of  the 
command  and  the  meaning  of  the  keyword(s)  and  data  in  the  command.  The  actual  SWAN  user 
commands  must  be  given  in  one  file  containing  all  commands.  This  file  is  called  the  command  file. 
It  must  be  presented  to  SWAN  in  ASCII  format.  The  proper  sequence  of  the  commands  is  given  in 
Section  4.12.1. 

Command  Keywords 

Each  command  instructs  SWAN  to  carry  out  a  certain  action,  which  SWAN  executes  before  it  reads 
the  next  command.  A  command  must  always  begin  with  a  keyword  (which  is  also  the  name  of  the 
command)  that  indicates  the  primary  function  of  that  command;  see  list  in  Section  4.12.1.  A 
simple  command  may  appear  in  its  command  scheme  as: 

KEYWORD  data 


A  command  may  contain  more  than  one  keyword  (which  refines  the  instructions  to  SWAN),  e.g., 
KEY1WORD  KEY2WORD  data 


where  KEY2 WORD  is  the  second  key  word. 

Spelling  of  keywords 

In  every  command  scheme,  keywords  appear  as  words  in  capital  letters  with  the  first  part  underlined 
(KEY  1  WORD  and  KEY2WORD  in  the  above  example).  When  typing  the  command  in  the  command 
file,  the  user  must  copy  the  underlined  part.  SWAN  reads  only  the  underlined  part  and  SWAN  is 
case  insensitive  except  for  one  instance  (character  strings),  see  below.  When  typing  the  keyword  in 
the  command  file,  any  extension  of  the  underlined  part  is  at  the  user’s  discretion  as  long  as  the 
extension  is  limited  to  letters  (upper-  and  lower  case)  or  digits  (but  not  underlined),  as  well  as  the 
characters  -  and  _.  So  in  the  command  outlined  above  one  may  write:  KEY  or  KEYW  or  KEY-word 
or  KEYHOLE  etc.  at  the  users  discretion. 

Example: 

KEY1WORD  KEY2WORD  data  (command  scheme): 


Keyl  KeY2  data  (command  file) 
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In  the  command  file,  a  keyword  is  closed  by  a  blank  or  by  =  or  :  .  Square  brackets  or  quotes  do  not 
enclose  it.  A  keyword  followed  by  a  comma  (,)  is  interpreted  as  a  keyword  followed  by  an  empty 
data  field  (see  below). 

Required  and  optional  keywords 

All  keywords  in  a  command  are  required  except  when  an  option  is  available.  Optional  keywords 
are  indicated  in  the  command  scheme  with  the  following  signs  enclosing  the  keywords  concerned: 

|  KEY1WORD  . data 

< 

|  KEY2WORD  . data 

For  the  above  example  it  may  appear  as: 

|  KEY2WORD  data  | 

KEY1WORD  <  > 

|  KEY 3 WORD  data  | 

In  case  the  user  does  not  indicate  an  option  in  a  command,  SWAN  chooses  the  alternative  indicated 
with  an  arrow  (  ->  )  appearing  in  the  command  scheme  (the  default  option).  In  the  above  example  it 
may  appear  as: 

|  KEY2WORD  data  | 

KEY 1 WORD  <  > 

|  ->  KEY3WORD  data  | 

where  KEY 3 WORD  is  the  default  option. 

Repetitions  of  keywords  and/or  other  data 

The  use  of  keywords  is  sometimes  repetitive,  such  as  in  a  sequence  of  data  and  keywords 
containing  many  locations  in  x-y  space.  In  this  case,  the  command  scheme  indicates  this  repetitive 
nature  by  placing  the  keywords  (and  data)  concerned  between  angle  brackets  <  >.  In  the  above 
example  it  may  appear  as: 


|  KEY2WORD  | 

KEY1WORD  <  data  <  >  data  > 

|  KEY3WORD  | 

The  user  must  give  such  a  sequence  in  the  actual  command  of  the  command  file.  It  ends  with  either 
the  end  of  the  line,  a  keyword  other  than  one  mentioned  in  the  repetition  group,  or  the  character  /  or 
; .  If  more  than  one  line  is  required  for  a  command,  the  user  may  continue  on  the  next  line  as 
described  below  ('end  of  line').  The  repetition  may  consist  of  one  instance  (in  fact,  no  repetition  at 
all). 
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Data 

Most  commands  contain  data,  either  character  data  or  numerical  data.  Character  data  (strings)  are 
represented  in  the  command  schemes  by  names,  enclosed  in  quotes  ('  ')•  Numerical  data  are 
represented  by  names  enclosed  in  square  brackets  ([  ]).  As  a  rule  an  error  message  will  result  if 
numerical  data  is  given  where  character  data  should  be. 

Spelling  of  character  data 

Character  data  are  represented  as  character  strings  (a  sequence  of  characters  and  blanks)  between 
quotes  in  the  command  scheme  and  in  the  command  file.  SWAN  interprets  an  end  of  the  line  as  an 
end  quote.  Therefore,  a  character  data  field  can  never  extend  over  more  than  one  line.  In  a 
command  scheme  the  character  string  is  always  a  name  that  is  placed  between  quotes.  In  the 
command  file  such  a  name  can  be  entered  in  two  ways: 

1.  Replace  the  name  by  another  character  string  at  the  user’s  discretion  (this  is  the  only  occurrence 
where  SWAN  is  case  sensitive;  e.g.,  for  text  to  appear  in  a  plot). 

Example: 

KEY1WORD  KEY2WORD  'City'  data  (command  scheme) 

KEY1  KEY2  '  Amsterdam- Ola '  data  (command  file) 

2.  Copy  the  name  of  the  variable  (without  the  quotes)  followed  by  an  =  sign  and  a  name  at  the 
user’s  discretion  (between  quotes).  SWAN  interprets  the  copied  name  in  the  command  file  as  a 
keyword,  as  if  it  were  fully  underlined  in  the  command  scheme  with  all  the  characteristics  of  a 
keyword,  such  as  ending  a  sequence  of  optional  data  (see  below).  As  with  other  keywords,  the 
name  of  the  variable  is  case-insensitive. 

Example: 

KEY1WORD  KEY2WORD  'City'  data  (command  scheme) 


KEY1WORD  KEY2WORD  City=  'Amsterdam- 01 '  data  (command  file) 


An  error  message  will  result  if  numerical  data  is  given  where  character  data  should  be  given. 
Spelling  of  numerical  data 

Numerical  data  are  simple  numbers,  e.g.,  15  or  -7  (integer  data),  or  13.7  or  0.8E-4  (real  data). 
Whether  or  not  an  integer  or  a  real  number  should  be  given  by  the  user  is  indicated  in  the 
description  of  the  command  scheme.  A  decimal  point  is  not  permitted  in  an  integer  number.  On 
the  other  hand,  SWAN  accepts  an  integer  number  where  a  real  number  should  be  given.  In  a 
command  scheme  the  number  is  always  indicated  with  a  name  (which  is  placed  between  square 
brackets).  In  the  command  file,  such  a  name  can  be  entered  in  two  ways: 
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1 .  Replace  the  name  by  a  number  (not  between  square  brackets). 

Example: 

KEY  1  WORD  KEY2WORD  [nnn]  (command  scheme) 

KEY1  KEY2  307  (command  file) 

2.  Copy  the  name  of  the  variable  (without  the  square  brackets)  followed  by  an  =  sign  and  the 
number  (not  between  square  brackets).  SWAN  interprets  the  copied  name  in  the  command  file 
as  a  keyword  (as  if  it  were  fully  underlined  in  the  command  scheme)  with  all  the  characteristics 
of  a  keyword  such  as  ending  a  sequence  of  optional  data  (see  below).  As  with  other  keywords, 
the  name  of  the  variable  is  case-insensitive. 

Example: 

KEY1WORD  KEY2WORD  [nnn]  (command  scheme) 

KEY  1  WORD  KEY2WORD  nnn=307  (command  file) 


Required  data  and  optional  data 

All  data,  given  by  the  user,  must  be  given  in  the  command  file  in  the  same  order  as  they  appear  in 
the  command  scheme.  Blanks  or  commas  separate  them.  Required  data  (indicated  in  the 
description  of  each  individual  command)  must  be  given  explicitly  as  character  strings  or  numbers. 


Optional  data  are  indicated  in  the  text  of  each  individual  command  or  by  parenthesis  around  the 
data  concerned.  For  example, 

KEY1WORD  KEY2WORD  'name'  ([nnn]  [mmm] )  [zzz] 

Some  optional  data  are  indicated  in  the  same  way  as  optional  keywords  are  indicated: 

|  . data .  | 

<  > 

|  . data .  | 

Optional  data  may  be  omitted  by  giving  blanks  between  commas,  and  SWAN  will  substitute 
reasonable  default  values.  If  all  data  after  a  required  datum  is  optional  (till  the  next  keyword  or  the 
next  end-of-line),  then  commas  may  be  omitted  as  well.  Optional  data  indicated  like  optional 
keywords  are  to  be  treated  as  optional  keywords. 
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Command,  file  and  comments 

All  text  after  one  $  or  between  two  $  signs  on  one  line  in  the  command  file  is  ignored  by  SWAN  as 
comment  text.  Such  comments  may  be  important  to  the  user,  e.g.,  to  clarify  the  meaning  of  the 
commands  used.  In  fact,  this  option  has  been  used  to  create  the  edit  file  SWAN.EDT  (see 
Appendix  C).  Any  text  appearing  after  two  $  signs  is  not  interpreted  as  a  comment  but  as  data  to  be 
processed  (possibly  interrupted  again  by  $  or  two  $  signs). 

End  of  line  or  continuation 

A  command  in  the  command  file  may  be  continued  on  the  next  line  if  the  previous  line  terminates 
with  a  continuation  mark 

&  or  _  (underscore) 
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Appendix  B  Run  instructions 

To  run  SWAN,  e.g.,  under  DOS,  UNIX  or  MS-WINDOWS,  talk  to  the  person  who  implemented 
SWAN  on  your  computer  system.  SWAN  is  to  be  implemented  by  following  the  instructions  in 
Section  4.0  or  by  using  the  implementation  manual  found  on  the  SWAN  web  site.  A  summary  of 
the  run  instructions  is  illustrated  in  the  following  figure. 
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Figure  B-l.  Flow  diagram  summarizing  the  steps  for  execution  of  SWAN  Version  40.1 1. 
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Appendix  C  File  SWAN.EDT 

PROJect  'name'  'nr' 

' titlel ' 

' title2 * 

' title3 ’ 


MODE  STATionary/NONSTat ionary  TWODimensional/ONEDimensional 

COORDinates  /  ->  CARTesian  \ 

\  SPHErical  CCM/QC  / 

SET  [level]  [nor]  [depmin]  [maxmes]  [maxerr]  & 

[grav]  [rho]  [inrhog]  [hsrerr]  & 

CARTesian/NAUTical  [pwtail]  [froudmax]  & 

[printf ]  [prtest] 

CGRID  /  REGular  [xpc]  [ypc]  [alpc]  [xlenc]  [ylenc]  [mxc]  [myc]  \ 

\  CURVilinear  [mxc]  [myc]  (  Exception  [xexc]  [yexc]  )  / 

/  CIRcle  \ 

\  SECtor  [dirl]  [dir2]  [mdc]  / 

[flow]  [fhig]  [msc] 

TEST  [itest]  [itrace]  & 

POINTS  IJ  <  [i]  [j]  >  /  XY  <  [x]  [y]  >  & 

(PAR  ' f name ’ )  (SID  • f name ' )  (S2D  ’ f name ' ) 

INPgrid  BOTtom/WLEVel/CURrent/VX/VY/FRiction/WInd/WX/WY  & 

/  REGular  [xpinp]  [ypinp]  [alpinp]  [mxinp]  [myinp]  [dxinp]  [dyinp]  \ 

\  CURVilinear  [stagrx]  [stagry]  [mxinp]  [myinp]  / 

(Exception  [excval]  ) 

(NONSTATionary  [tbeginp]  [deltinp]  Sec/MIn/HR/DAy  [tendinp] ) 

READ  BOTtom/WLevel / CURrent / FRict ion/WInd/ COORdinates  & 

fnamel 1 /SERIES  '  f name2  1  [idla]  [nhedf]  (  [nhedt]  )  (nliedvec]  )  & 
/  FREe  \ 

<  FORmat  ’ form' / [idfm]  > 

\  UNFormatted  / 

WIND  [vel]  [dir] 


BOUNdparl  SHAPespec  JON  [gamma]  /  PM  /  GAUSS  [sigfr]  /  BIN 
PEAK/MEAN  DSPR  POWER/DEGRees 


B0UNdpar2  /  SIDE  N/NW/W/SW/S/SE/E/NE  CCW/CLOCKWise  \ 
\  SEGMent  XY  <  [x]  [y]  >  /  IJ  <  [i]  [j]  >  / 
/  CONSTANT  PAR  [hs]  [per]  [dir]  [dd]  \ 

\  VARIABLE  PAR  <  [len]  [hs]  [per]  [dir]  [dd]  >  / 

BOUNdspec  /  SIDE  N/NW/W/SW/S/SE/E/NE  CCW/CLOCKWise  \ 
\  SEGMent  XY  <  [x]  [y]  >  /  IJ  <  [i]  [j]  >  / 
/  CONSTANT  FILE  1 f name '  [seq]  \ 

\  VARIABLE  FILE  <  [len]  ' f name '  [seq]  >  / 

BOUNdnestl  NEst  'fname'  CLOSed/OPEN 


BOUNdnest2  WAMNest 
[xgc]  [ygc] 


fname’  /  UNFormatted  CRAY/WKstat  \ 
\  FREe  / 


& 


& 


& 
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BOUNdnest3  WW3  1 f name •  CLOSed/OPEN  ( [xgc]  [ygc] ) 

/  DEFault 
INITial  <  ZERO 

\  PAR  [hs]  [per]  [dir]  [dd] 

\  HOTStart  ' f name ’ 

GEN1  [cf 10]  [cf 2  0]  [cf 3  0]  [cf40]  [edmlpm]  [cdrag]  [umin]  [cfpm] 

GEN 2  [cf 10]  [cf 20]  [cf 30]  [cf40]  [cf50]  [cf60]  & 

[edmlpm]  [cdrag]  [umin]  [cfpm] 

GEN3  /  KOMen  [cds2]  [stpm]  \ 

\  JANSsen  [cdsl]  [delta]  /  & 

(QUADrupl  [iquad]  [lambda]  [cnl4]  [cshl]  [csh2]  [csh3] )  & 

(AGROW  [a] ) 

BREaking  CONstant  [alpha]  [gamma] 

/  JONswap  [cfjon] 

FRICtion  <  COLLins  [cfw] 

\  MADsen  [kn] 

TRIad  [trfac]  [cutfr] 

OBSTacle  (TRANSm  [trcoef]  /  DAM  [hgt]  [alpha]  [beta] )  & 

(REFL  [reflc] )  LINE  <  [xp]  [yp]  > 

SETUP  [supcor] 

OFF  BREaking  /  WCAPping  /  REFrac  /  FSHift  /  QUADrupl  /  WINDGrowth 
PROP  ??  T  /  SORDup  \  NONST  /  STELling  [waveage]  Sec/MIn/HR/DAy  \ 


\  BSBT  /  \  BSBT  / 

NUMeric  (  ACCUR  [drel]  [dhabs]  [dtabs]  [npnts]  & 

/  ->  STATionary  [mxitst]  \ 

\  NONSTationary  [mxitns]  /  [limiter]  )  & 

(DIRimpl  [cdd]  [cdlim]  )  & 

(SIGIMpl  [css]  [prec]  [epsl]  [eps2]  [outp]  [niter] )  & 

(SETUP  rpec]  [eps2]  [outp]  [niter] ) 

FRAme  1 sname '  [xpfr]  [ypfr]  [alpfr]  [xlenfr]  [ylenfr]  & 

[mxfr]  [myfr]  [scale] 


GROUP  'sname*  SUBGrid  [ixl]  [ix2]  [iyl]  [iy2] 

NGRid  'sname'  [xpn]  [ypn]  [alpn]  [xlenn]  [ylenn]  [mxn]  [myn] 

CURve  'sname'  [xpl]  [ypl]  <  [int]  [xp]  [yp]  > 

POINts  ' sname '  <  [xp]  [yp]  >  /  FILE  ' f name ' 

RAY  ' rname '  [xpl]  [ypl]  [xql]  [yql]  & 

<  [int]  [xp]  [yp]  [xq]  [yq]  > 

ISOline  'sname'  'rname'  DEPth/BOTtom  [dep] 

LINe  CONTinuous  /  DAShed  [pat]  [len]  & 

(COLor  [ipen]  )  <  [xp]  [yp]  > 
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SITES 


<  ' pname '  [xp]  [yp]  [size]  REGion  /  TOWN  > 


QUANTity  DSPR/HSign/DIR/PDIR/TDIR/TM0l/RTM01 /RTP/TM02 /FSPR/PER/RPER/ 

DEPth/VEL/FRCoef f/WIND/DISSip/QB/TRAnsp/FORce/UBOT/URMS/WLEN/ 
STEEpness/HSWEll/DHSign/DRTMOl/LEAK/XP/YP/DIST 
'short'  'long'  [lexp]  [hexp]  [excv] 

([power])  ([ref])  ( [fswell] ) 

( PROBLEMcoord/ FRAME) 


BLOck  'sname'  HEADer  /  NOHEADer  ' f name '  (LAYout  [idla] ) 

<  DSPR/HSign/DIR/PDIR/TDIR/TM0l/RTM0l/RTP/TM02 /FSPR/PER/RPER/ 

DEPth/ VEL/ FRCoe f  f / WIND/DI SS ip/QB/TRAnsp / FORce /UBOT/URMS /WLEN / 
STEEpness/HSWEl 1 / DHSign/DRTMO 1 / LEAK  [unit]  > 

(OUTput  [tbegblk]  [deltblk]  Sec/MIn/HR/DAy) 

TABle  'sname'  HEADer  /  NOHEADer  /  INDexed  'fname' 

<  DSPR/HSign/DIR/PDIR/TDIR/TM01/RTM01/RTP/TM02 /FSPR/PER/RPER/ 

DEPth/VEL/FRCoef f /WIND/DI SS ip/QB/TRAnsp /FORce /UBOT/URMS /WLEN/ 
STEEpness/HSWEl 1 /DHSign/DRTMO l/LEAK/XP/YP/DIST  > 

(OUTput  [tbegtbl]  [delttbl]  Sec/MIn/HR/DAy) 

SPECout  'sname'  SPEC1D/SPEC2D  ABs/REl  'fname' 

(OUTput  [tbegspc]  [deltspc]  Sec/MIn/HR/DAy) 


NESTout  ' sname '  ' fname ' 

(OUTput  [tbegnst]  [deltnst]  Sec/MIn/HR/DAy) 

PLOtgeogr  'sname'  (File  'fname')  'title'  (COORD  [marg] ) 

ISO  DSPR/HSign/TM0l/RTM01/RTP/TM02/FSPR/PER/RPER/DEPTH/ 
FRCoef f/DISSip/QB/UBOT/URMS/WLEN/ STEEpness/HSWEll/ 
DHSign/DRTMOl/LEAK  [step]  [min]  [max] 

VEC  VEL/TRAnsp/FORce/WIND/DIR/PDIR/TDIR  [scale]  [dist] 
(CMESH)  [ipen]) 

(SITes  [ipen])  (LINes  [ipen])  (Location  ('sname')  [ipen]) 

(OUTput  [tbegnst]  [deltnst]  Sec/MIn/HR/DAy) 

PLOtstar  'sname'  (File  'fname')  'title'  (COORD  [marg]) 

ISO  DSPR/HSign/TM0l/RTM01/RTP/TM02 /FSPR/PER/RPER/ DEPTH/ 
FRCoef f/DISSip/QB/UBOT/URMS/WLEN/STEEpness/HSWEll/ 
DHSign/DRTMOl/LEAK  [step]  [min]  [max] 

STAR  [scale]  [dist]  [bundle] 

(CMESH)  [ipen] ) 

(SITes  [ipen])  (LINes  [ipen])  (Location  ('sname')  [ipen]) 

(OUTput  [tbegnst]  [deltnst]  Sec/MIn/HR/DAy) 

PLOtpp  'sname'  File  'fname'  'title' 

PROBlems  FROUDe  /  PCONV  [symsiz] 

(SITes  [ipen] )  (LINes  [ipen] )  (Location  ( 'sname' )  [ipen] ) 

(OUTput  [tbegnst]  [deltnst]  Sec/MIn/HR/DAy) 

PLOtspec  'sname'  (File  'fname')  'title' 

SPECtrum  NORMalized  /  NONORM  (  <  [ch]  >  ) 

FReq  NORm  /  [fmax]  [fmid]  ABS/REL 

(OUTput  [tbegnst]  [deltnst]  Sec/MIn/HR/DAy) 


& 


& 


Sc 


Sc 


Sc 


Sc 


Sc 


Sc 

Sc 

Sc 

Sc 


Sc 


Sc 

Sc 

Sc 

Sc 


Sc 

Sc 

Sc 


Sc 

Sc 

Sc 


COMPUTE 

COMPUTE  STATionary  [time] 

$  COMPUTE  NONSTat  [tbegc]  [deltc]  Sec/MIn/HR/DAy  [tendc] ) 

$ 

$  HOTFile  'fname' 
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POOL 

STOP 
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Appendix  D  Spectrum  files,  input  and  output. 


This  appendix  describes  the  format  of  the  files  for  spectral  input  (command  BOUNDARY)  and 
output  (commands  SPEC  and  NEST)  by  SWAN.  The  presence  of  the  keyword  SWAN  and  a 
version  number  recognize  the  files  on  the  first  line  of  the  file.  This  description  is  valid  for  version 
number  1. 


These  files  contain  the  following  information: 

•  coordinates  of  locations. 

•  frequencies. 

•  directions  (if  used  for  2-D). 

•  time  (if  time-dependent). 

•  spectral  energy  or  variance  densities  (and  aver.  dir.  and  dir.  spread  if  1-D). 

Example  of  a  1-1)  nonstationarv  spherical  coordinates  file: 


SWAN  1 

$  Data  produced  by  SWAN  version  40.1 1 

$  Project:'projname'  ; 

TIME 

1 

LONLAT 

2 

1.00  1.00 

1.20  1.00 

RFREQ 

25 

0.0418 

0.0477 

0.0545 

0.0622 

0.0710 

0.0810 

0.0924 

0.1055 

0.1204 

0.1375 

0.1569 

0.1791 

0.2045 

0.2334 

0.2664 

0.3040 

0.3470 


Swan  standard  spectral  file,  version 

run  numben'runnum' 

time-dependent  data 

time  coding  option 

locations  in  spherical  coordinates 

number  of  locations 


relative  frequencies  in  Hz 
number  of  frequencies 
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0.3961 

0.4522 

0.5161 

0.5891 

0.6724 

0.7675 

0.8761 

1.0000 

QUANT 

3 

VaDens 

m2/Hz 

-0.9900E+02 

CDIR 

degr 

-0.9990E+03 

DSPRDEGR 

degr 

-0.9000E+01 

19680606.030000 

LOCATION  1 


0.3772E-03 

190.1 

6.3 

0.1039E-02 

190.2 

6.5 

0.228  IE-02 

190.3 

6.7 

0.3812E-02 

190.3 

6.7 

0.4255E-02 

190.3 

6.6 

0.2867E-02 

190.1 

6.3 

0.1 177E-02 

189.6 

5.8 

0.3892E-03 

192.0 

15.2 

0.8007E-03 

244.5 

22.9 

0.601 6E-02 

251.4 

11.5 

0.1990E-01 

251.0 

11.0 

0.3698E-01 

249.9 

10.9 

0.3874E-01 

248.1 

12.1 

0.2704E-01 

246.6 

13.0 

0.1672E-01 

247.0 

13.5 

0.1066E-01 

247.7 

13.7 

0.5939E-02 

247.3 

14.0 

0.3247E-02 

246.5 

14.6 

0.1697E-02 

245.9 

14.9 

0.8803E-03 

245.6 

15.1 

0.454 IE-03 

245.5 

15.3 

0.2339E-03 

245.4 

15.5 

0.1197E-03 

245.5 

15.6 

number  of  quantities  in  table 
variance  densities  in  m2/Hz 
unit 

exception  value 

average  Cartesian  direction  in  degr 
unit 

exception  value 
directional  spreading 
unit 

exception  value 
date  and  time 
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0.6129E-04 

0.3062E-04 

LOCATION  2 
0.7129E-02 
0.3503 E-01 
0. 1 299E+00 
0.5623E+00 
0.1521E+01 
0.3289E+01 
0.4983E+01 
0.4747E+01 
0.2322E+01 
0.1899E+01 
0.1900E+01 
0.6038E+01 
0.8575E+01 
0.4155E+0I 
0.1 109E+01 
0.7494E+00 
0.4937E+00 
0.2953E+00 
0.1661E+00 
0.9788E-01 
0.5766E-01 
0.3397E-01 
0.2001  E-01 
0.1 179E-01 
0.6944E-02 


245.5 

15.7 

245.3 

15.9 

67.2 

25.3 

67.5 

21.7 

68.2 

19.7 

69.7 

18.0 

71.4 

18.0 

74.0 

18.8 

77.2 

20.3 

79.9 

22.0 

79.4 

30.7 

341.1 

56.2 

314.6 

39.4 

324.3 

31.9 

326.1 

31.0 

325.1 

30.5 

322.8 

32.9 

323.1 

33.3 

323.1 

33.3 

323.3 

33.7 

323.6 

34.0 

323.7 

33.8 

323.8 

33.6 

324.0 

33.5 

324.1 

33.4 

324.2 

33.3 

324.2 

33.2 

Example  of  a  2-D  stationary  Cartesian  coordinates  file  : 


SWAN  1 

$  Data  produced  by  SWAN  version  40. 
$  Project:  'projname' 

LOCATIONS 

2 

0.00  0.00 

22222.22  0.00 

RFREQ 

25 

0.0418 

0.0477 

0.0545 

0.0622 


Swan  standard  spectral  file,  version 

11 

run  number:  'runnum' 
locations  in  x-y-space 
number  of  locations 


relative  frequencies  in  Hz 
number  of  frequencies 
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CDIR 


0.0710 

0.0810 

0.0924 

0.1055 

0.1204 

0.1375 

0.1569 

0.1791 

0.2045 

0.2334 

0.2664 

0.3040 

0.3470 

0.3961 

0.4522 

0.5161 

0.5891 

0.6724 

0.7675 

0.8761 

1.0000 

spectral  Cartesian  directions  in  degrees 
24  number  of  directions 

7.5000 

22.5000 

37.5000 

52.5000 

67.5000 

82.5000 

97.5000 

112.5000 

127.5000 

142.5000 

157.5000 

172.5000 

187.5000 

202.5000 

217.5000 

232.5000 

247.5000 

262.5000 

277.5000 

292.5000 

307.5000 

322.5000 
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337.5000 

352.5000 
QUANT 

1  number  of  quantities  in  table 

VaDens  variance  densities  in  m2/Hz/degr 

m2/Hz/degr  unit 

-0.9900E+02  exception  value 


FACTOR 

0.422574E-1 1 
0  0  0  0 
0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 

0  0  0  0 


0 

0 

0 

0 

0 

0 

0 

0 

1 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

44 

3 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

817 

60 

1 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

8018 

574 

9 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

39230 

2532 

38 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

92174 

4477 

68 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

99010 

1946 

29 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

47054 

131 

2 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

13228 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

39417 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

61269 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

29738 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

2161 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

2 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 
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0 

0 

0 

0 

0 

0 

0 

0 

0  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

FACTOR 

0.67561  IE-06 

51 

242 

574  ' 

956  1288 

1482 

1481 

1286 

957 

579 

244 

51  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

129 

610 

1443  2402  3238 

3725 

3724 

3234 

2406 

1454 

613  : 

128  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

273  1287 

3054  5084  6846 

7872 

7869 

6837 

5091 

3076 

1295 

271  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

665  3152 

7463  12402  16712  19229  19221  16690  12419 

7518 

3172 

662  0  0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

1302 

6159 

14608 

24275 

32688  37618  37603 

32644  24309 

14716 

6198 

1296 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

2328  10989  26020  43341 

58358  67109  67080  58281 

43401  26213  11058 

2317 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

3365  15922  37712 

62733 

84492  97150  97110 

84380 

62820  37991  16021 

3349 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

1 

3426  16230  38440 

63939 

86109  99010  98969 

85995 

64027  38724  16331 

3410 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

1 

2027 

9612 

22730 

37790 

50909  58529  58505 

50841 

37843  22898 

9672 

2018 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

1 

672 

3178 

7538 

12535 

16892  19440  19432 

16870 

12552 

7594 

3198 

669 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

101 

479 

1135 

1890 

2542  2924  2923 

2539 

1892 

1144 

482 

101 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

2 

11 

26 

43 

57 

66 

66 

57 

43 

26 

11 

2 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

1 

1 

1 

1 

1 

1 

0 

0 

0 

0 

0 

0 
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0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 
0  0  0  0 
0  0  0  0  0 


0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 
0  0  0  0 


0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 
0  0  0  0  0  0 


Note  that  the  true  variance  or  energy  densities  are  obtained  by  multiplying  each  number  with  the 
factor  given  under  the  keyword  FACTOR. 

Formal  description  of  the  1-D  and  2-D  spectral  file 


0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 


This  description  refers  to  either  write  or  read  energy/variance  density  spectra  to  or  from  the  file. 

The  description  of  the  file  to  write  or  read  source  terms  is  identical  to  this  description  except  that 
the  quantities  differ. 

FREE  FORMAT  (FORTRAN  convention)  is  the  format  used  by  SWAN  or  the  user  when  offering 
the  file  to  SWAN,  except  that  all  keywords  and  names  of  quantities  (see  below)  should  start  on  the 
first  position  of  the  line  on  which  they  appear  (see  Appendix  A  for  the  syntax  of  keywords).  This 
format  implies  that  SWAN  ignores  all  information  on  each  line  after  the  required  input  for  SWAN. 
This  can  be  used  to  enter  user's  information  at  the  discretion  of  the  user. 

1st  line:  the  keyword  “SWAN”  followed  by  the  version  number 

2nd  line:  If  nonstationary  computations:  the  keyword  “TIME”. 
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If  stationary  computations:  not  present. 

3ro  line:  If  nonstationary  computations:  a  number  which  is  the  time  coding  option.  It  is 

recommended  to  use  1  (ISO  notation). 

If  stationary  computations:  not  present. 

4th  line:  The  description  of  the  locations: 

If  using  Cartesian  coordinates  the  keyword  “LOCATIONS”. 

If  using  spherical  coordinates  the  keyword  “LONLAT”. 

Number  of  locations. 

If  using  Cartesian  coordinates: 

For  each  location  give  an  x-  and  y-coordinate  (in  m,  Cartesian  (problem) 
coordinates). 

If  the  file  is  used  for  input  to  SWAN  (but  not  generated  by  SWAN)  and  the 
user  so  desires,  the  names  of  locations  can  be  written  behind  the  two 
coordinates.  These  names  are  ignored  by  SWAN  when  reading  the  file  (see 
remark  on  format  above). 

If  using  spherical  coordinates: 

For  each  location  give  longitude  and  latitude. 

If  the  fde  is  used  for  input  to  SWAN  (but  not  generated  by  SWAN)  and  the 
user  so  desires,  the  names  of  locations  may  be  entered  behind  the  two 
coordinates.  These  names  are  ignored  by  SWAN  when  reading  the  file. 

Next:  The  frequency  data  (for  1-D  and  2-D  spectra): 

The  keyword  “AFREQ”  or  “RFREQ”  (to  distinguish  between  abs.  and  rel.  freq.). 
Number  of  frequencies. 

A  column  with  frequencies  (each  on  a  new  line)  always  in  Hz. 

Next:  The  direction  data  (only  for  2-D  spectra  in/output): 

The  keyword  “NDIR”  or  “CDIR”  (to  distinguish  between  Nautical  and  Cartesian 
direction). 

Number  of  directions. 

A  column  with  directions  (each  on  a  new  line)  always  in  degrees. 

Then  The  group  describing  the  quantities  in  the  tables  of  this  file  (see  the  above  examples): 
The  keyword  “QUANT”. 

Number  of  quantities. 

For  each  quantity: 

Name  of  the  quantity. 

Unit  of  the  quantity. 

Exception  value  of  the  quantity,  i.e.,  the  value  that  is  written  instead  of  a 
computed  value  if  that  is  undefined  (not  computed,  such  as  mean 
wave  direction  if  the  wave  energy  is  zero) 

XXX:  Note  for  1-D  spectra: 
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The  number  of  quantities  is  always  3,  and  the  quantities  are  always  energy  (or 
variance)  density,  average  direction  (CDIR  for  Cartesian  direction  and  NDER  for 
Nautical  direction)  and  directional  spread  (DSPR  in  terms  of  DEGREES). 
(SWAN  writes  the  keyword  “DSPRDEGR”.  SWAN  reads  the  keywords 
“DSPRD”  or  “DEGR”  in  case  of  option  DEGREES  or  the  keywords  “DSPRP” 
or  “POWER”  in  case  of  option  POWER  in  command  BOUNDPAR1).  The 
quantities  appear  in  the  order  in  which  they  appear  in  this  description. 

Note  for  2-D  spectra: 

The  number  of  quantities  is  always  1 .  The  quantity  is  always  energy  or  variance 
density  (“EnDens”  is  the  (short)  name  of  true  energy  densities,  “VaDens”  for 
variance  densities). 

Then:  The  group  with  the  tables  of  the  quantities: 

WV  Date  and  time  (not  present  for  stationary  computations). 

For  each  location: 

If  2-D  spectrum: 

•  The  keyword  “FACTOR”.  FACTOR  is  replaced  by  the  keyword 
ZERO  if  the  spectrum  is  identical  0.  FACTOR  is  replaced  by 
NODATA  if  the  spectrum  is  undefined  (not  computed,  as  on  land 
and  no  numbers  follow). 

•  The  factor  to  multiply  the  values  in  the  following  table. 

•  Scaled  energy/variance  densities  (truncated  by  SWAN  to  integer 
values  for  compact  writing.  SWAN  accepts  these  values  as  reals 
when  reading  this  file.  Other  programs  e.g.,  for  postprocessing, 
should  also  accept  these  values  as  reals.  The  values  should  be 
multiplied  by  the  factor  to  get  the  proper  values  of  the  densities. 

Else,  if  1  -D  spectrum: 

•  The  keyword  LOCATION  followed  by  the  index  of  the  location 
(on  the  same  line).  This  is  replaced  by  the  keyword  NODATA  if 
the  spectrum  is  undefined  (not  computed  e.g.  on  land.  No 
numbers  follow). 

•  Else,  a  table  containing  three  columns.  The  three  quantities  per 
frequency:  energy  (or  variance)  density,  average  direction  (CDIR 
for  Cartesian  direction  and  NDIR  for  Nautical  direction)  and 
directional  spread  (DSPR  in  terms  of  DEGREES  (writing  or 
reading  the  file)  or  POWER  (only  reading  the  file),  see  XXX). 

The  quantities  appear  in  the  order  in  seen  in  this  description. 

For  nonstationary  computations  repeat  from  VVV. 
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Appendix  E  Acronyms 


ASCE 

BSBT 

CCM 

DIA 

DTA 

GSE 

HPGL 

LTA 

OPPL 

SORDUP 

S&L 

SWAN 


American  Society  of  Civil  Engineering 
Backward  Space-Backward  Time  Scheme 
Central  Conformal  Mercator 
Discrete  Interaction  Approximation 
Discrete  Triad  Approximation 
Garden  Sprinkler  Effect 
HP  Graphick  Language 
Lumped  Triad  Approximation 
Ocean  Pack  Plot  Code 
Second  Order  Upwind  Scheme 

Stelling  and  Leendertse’s  Second  Order  with  Third-Order  Diffusion  Scheme 
Simulating  Waves  Nearshore 
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